docs(readme): slim the root README to a reader's page — contributor detail to CONTRIBUTING.md, stale lines out, ui/ named MIT (#26148)

<!-- claude-projects-attribution: {"github_login":"os-steve"} -->
_Requested by **Steve** · [project
thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi9VtPHVbfSWDg4vBhPwGkgzA)_
Fixes #26129
Clause-②: no
Metadata-protocol: none

## Summary

Root README slimmed from 464 to **277 lines** (`wc -l README.md`, head
`b650e87e`). Contributor detail moves to `CONTRIBUTING.md` verbatim; the
three stale lines go; one architecture figure stays; the ObjectOS line
and the licensing wording follow the scope amendment (comment
6417139067, the maintainer's edition ruling); `LICENSING.md` names `ui/`
as MIT. Docs-only: `skip-changeset`.

## Per scope item

1. First screen: quote block, tag line, GIF, "Try it in five minutes"
unchanged except the deletions below.
2. Quote block loses "Ontology-driven: database, API, UI and agent tools
all derive…" and "Apps small enough for AI to hold whole."; the
`architecture.png` block is deleted (file kept); `layers.png` stays; the
StackBlitz sentence now sits above step 1.
3. "What we mean by ontology" is one paragraph: the definition, what it
is not, links to `concepts/ontology` and `concepts/compare`. See
deviation 3 for the metadata-driven paragraph.
4. Capability table and `Ticket` block kept; both `curl` blocks and the
`client-react` sentence deleted.
5. The `find … | wc -l` command is replaced by the measured number:
**1,873 lines of TypeScript** (30 files under `examples/app-crm/src`,
`*.test.ts` excluded, at `95294be3`), measured with the README's own
command.
6. "You own it": everything needed to run an app is in this repository;
Cloud and Enterprise add hosting and multi-environment operations, Build
& Ask, SSO and support. The license sentence is byte-identical in README
and LICENSING.md: "Apache-2.0, except `ui/` (the Console and
`@object-ui/*`), which is MIT — both permissive" (`grep -cF` → README 2,
LICENSING.md 1).
7. "Hack on the framework": the six-line command block plus the one
sentence from the card, linking `CONTRIBUTING.md#build-and-test-cost`.
The `console:build` paragraph, the measured table and the `--affected`
paragraph moved verbatim to the new `CONTRIBUTING.md` section "Build and
Test Cost" (30 original lines, `count == 1` in CONTRIBUTING.md).
8. Three layers kept; "ObjectUI" links to `ui/`.
9. CLI table unchanged.
10. Console row now reads "Prebuilt Console SPA, version-locked to this
release; built from `ui/apps/console` in this repository" (in the moved
package directory, see deviation 1).
11. Community: `ROADMAP.md` link replaced by the North Star concept
page; a GitHub Discussions line added (`has_discussions: true` on the
repository).

Amendment, scope item 1: the ObjectOS sentence under the GIF now names
the three editions in one sentence with two links (objectos.ai and the
Ship-it section).

## Deviations (declared, for the seat's ruling)

1. **The package directory moved to
`CONTRIBUTING.md#package-directory`**, verbatim (still a collapsed
details block; the only changed row is item 10's Console row), and
README keeps a two-line pointer. Reason: with items 2–11 applied and the
directory left in place, README measured **397 lines**, and the
directory alone is 128 lines. Under 300 cannot be reached while it
stays. It is not on the Acceptance list of blocks that must stay in
README. If the seat wants it back, revert that one hunk: README goes
back to about 400 lines and Acceptance line 1 fails.
2. "Other examples: `pnpm dev:crm`, `pnpm dev:todo` …" moved with the
build section. The sentence "AGENTS.md is the working rulebook …;
CONTRIBUTING.md covers the workflow" was dropped, because
CONTRIBUTING.md already opens with that statement.
3. **Item 3's premise does not hold**: the metadata-driven paragraph is
not in `concepts/ontology`. `grep -rn 'previous generation\|names the
mechanism' content/` gives 0 hits. The closest text is
`concepts/compare` "Metadata-driven application platforms → The
difference", which the new paragraph links. The paragraph is deleted as
the card asks; `content/` is outside this card's file surface, so if its
wording should survive somewhere it needs a docs card.
4. Bounded in-place fixes, same class as the card (root-doc lines that
contradict the tree or the edition ruling), all inside the declared file
surface: the README Community ObjectOS line ("the commercial runtime" →
ObjectOS Cloud) and the LICENSING.md ObjectOS paragraph ("not part of
this repository" → Community is this repository; Cloud and Enterprise
are commercial). Without these two, the new first-screen sentence would
contradict them. Also: the README License section now uses the same
license sentence; CONTRIBUTING step 1 drops its `ROADMAP.md` pointer;
two CONTRIBUTING lines that pointed at the README's build table and
package directory now point inside CONTRIBUTING.

## Acceptance notes

- Out of scope, untouched: README line "target an ObjectStack Cloud
control plane" (#26136 carries it), `ui/README.md` (#26080), badge row,
organisation profile.
- External links: this container's egress gives no answer for
`objectstack.ai` / `objectos.ai` / shields (curl `000`), so they are NOT
MEASURED online. CI's `Check Links` runs lychee `--offline` (internal
links only). The two new external targets were checked from other
evidence: Discussions is enabled (repository API), and
`/docs/concepts/north-star` is `content/docs/concepts/north-star.mdx`,
listed in `concepts/meta.json`.

## Verification (head `b650e87e`)

- `wc -l README.md` → 277 (under 300).
- Links: a local resolver over README.md, CONTRIBUTING.md and
LICENSING.md checked 124 internal links and their `#fragments` with 0
bad. A control file with one missing file and one bad fragment made it
report 2 bad and exit 1.
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` → 9 families, all exit 0:
`check-closing-keyword-parity` (scan and `--self-test`),
`check-comment-mask-corpus`, `check:doc-anchors` (601 fragment links
resolve; README.md is in its sources), `check:driver-memory-census`,
`check:gitlink-declared`, `check:nul-bytes`, `check:refd-timer-probe`,
`check:watch-hint-literal`. `--ran` reconciliation: 9 derived, 9 run, 0
NOT-MEASURED.
- No package or type-check surface touched; the type-check lanes are
left to CI.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01RCk6dPzGgXCem5gzzuQJ61)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

CONTRIBUTING.md

@@ -15,8 +15,10 @@ matters, it points you to AGENTS.md, and if the two ever disagree, AGENTS.md win
 
 - [Code of Conduct](#code-of-conduct)
 - [Getting Started](#getting-started)
+- [Build and Test Cost](#build-and-test-cost)
 - [Making a Change](#making-a-change)
 - [Where Things Live](#where-things-live)
+- [Package Directory](#package-directory)
 - [Pull Request Process](#pull-request-process)
 - [Community](#community)
 
@@ -58,16 +60,48 @@ pnpm build
 ```
 
 The README's [Hack on the framework](./README.md#hack-on-the-framework) section
-covers the rest: building the Console, running an example app with `pnpm dev`, and
-how long a first build and a full test run take.
+has the commands for building the Console and running an example app with `pnpm dev`;
+the next section says what each one costs.
+
+## Build and Test Cost
+
+`pnpm console:build` builds the Console from its source in this workspace
+(`ui/apps/console`, against this tree's own spec and client) and copies the
+result into `packages/console/dist` (gitignored), which is where `pnpm dev`
+serves it from. Nothing is cloned or pinned. `pnpm build` builds the Console
+too but does not copy it, so after `pnpm build` this step is a copy. Skip it
+and `pnpm dev` still serves the REST API, without the Console. Rerun it after
+pulling changes under `ui/`: `packages/console/dist` is never refreshed on its
+own.
+
+A first run is slow, not stuck. Measured once on a fresh clone of `main`
+(4-vCPU container, Node 22.22, pnpm 10.31):
+
+| Command | Time | |
+|:---|---:|:---|
+| `pnpm install` | 16 s | |
+| `pnpm build` | 6 m 54 s | 72 turbo tasks |
+| `pnpm console:build` | 12 m 16 s | 72 turbo tasks: the Console and what it depends on, run before any `pnpm build` (`--concurrency=2`); a cache hit plus a copy, about 1 s, once `pnpm build` has run |
+| `pnpm test` | 54 m 03 s | the full suite: 135 turbo tasks |
+
+For your own change, test what it reaches instead of the full suite:
+
+```bash
+pnpm turbo run test --affected          # packages your branch changes, and their dependents
+pnpm --filter @objectstack/<pkg> test   # one package
+```
+
+`--affected` compares your branch with your local `main`, so a stale `main`
+widens the set; keep it current, or set `TURBO_SCM_BASE=origin/main`.
+
+Other examples: `pnpm dev:crm`, `pnpm dev:todo`. Docs site: `pnpm docs:dev`.
 
 ## Making a Change
 
 1. **Start from an issue.** Pick one from the
    [issue tracker](https://github.com/objectstack-ai/objectstack/issues), or open one
    that describes the bug or the proposal before you write code.
-   [ROADMAP.md](./ROADMAP.md) and [docs/NORTH-STAR.md](./docs/NORTH-STAR.md) show
-   where the project is going.
+   [docs/NORTH-STAR.md](./docs/NORTH-STAR.md) shows where the project is going.
 2. **Branch off an up-to-date `main`, one branch and one pull request per issue**,
    with the issue number in the branch name:
 
@@ -105,16 +139,145 @@ how long a first build and a full test run take.
 | Path | What it holds |
 |:---|:---|
 | `packages/spec/src/` | The protocol: Zod schemas, types and constants. AGENTS.md lists the domains. |
-| `packages/`, `packages/plugins/`, `packages/services/`, … | The kernel, runtime, drivers, plugins, services, CLI and SDK. The README's package directory has them all. |
+| `packages/`, `packages/plugins/`, `packages/services/`, … | The kernel, runtime, drivers, plugins, services, CLI and SDK. The [package directory](#package-directory) below has them all. |
 | `content/docs/` | The documentation site's pages, in trees such as `getting-started/`, `concepts/`, `data-modeling/`, `ui/`, `automation/`, `api/` and `deployment/`. Preview with `pnpm docs:dev`. |
 | `content/docs/references/` | Generated from the Zod schemas by `packages/spec/scripts/build-docs.ts`. Never edit it by hand. |
 | `content/docs/releases/` | Written at release time from changesets. Never edit it in a code pull request. |
-| `examples/` | The example apps. The README's *Examples* table describes each one. |
+| `examples/` | The example apps. The *Examples* table in the [package directory](#package-directory) describes each one. |
 | [ARCHITECTURE.md](./ARCHITECTURE.md) | Design details, the plugin lifecycle and the dependency graph. |
 
 AGENTS.md (*Documentation Guardrails*) has the rules for every docs path, including what a
 new page needs before it shows up in the navigation.
 
+## Package Directory
+
+<details>
+<summary><b>Everything in <code>packages/</code></b>, grouped by layer — click to expand.</summary>
+
+#### Protocol & core
+
+| Package | Description |
+| :--- | :--- |
+| [`@objectstack/spec`](packages/spec) | The protocol — Zod schemas, TypeScript types, JSON Schemas, constants |
+| [`@objectstack/core`](packages/core) | Microkernel — plugin system, DI container, EventBus, Logger |
+| [`@objectstack/types`](packages/types) | Shared interfaces describing the runtime environment |
+| [`@objectstack/formula`](packages/formula) | Expression engine — CEL plus the ObjectStack stdlib, for formulas, predicates, defaults |
+| [`@objectstack/platform-objects`](packages/platform-objects) | Built-in platform objects — identity, security, audit, tenant, metadata |
+| [`@objectstack/lint`](packages/lint) | Static validation of a metadata graph, shared by `os validate` and AI authoring |
+| [`@objectstack/sdui-parser`](packages/sdui-parser) | Constrained JSX source → SDUI schema tree compiler (parse, never execute) |
+
+#### Engine
+
+| Package | Description |
+| :--- | :--- |
+| [`@objectstack/objectql`](packages/objectql) | Isomorphic ObjectQL query engine and schema registry |
+| [`@objectstack/runtime`](packages/runtime) | Runtime bootstrap — DriverPlugin, AppPlugin, environment artifacts |
+| [`@objectstack/rest`](packages/rest) | Auto-generated REST API layer |
+| [`@objectstack/metadata`](packages/metadata) | Metadata loading, saving, and persistence |
+| [`@objectstack/metadata-core`](packages/metadata-core) | Metadata repository contracts — types, canonicalization, errors |
+| [`@objectstack/metadata-fs`](packages/metadata-fs) | File-system metadata repository (JSON files + JSONL change log) |
+| [`@objectstack/metadata-protocol`](packages/metadata-protocol) | Metadata management protocol — CRUD, draft/publish, locks, diagnostics |
+| [`@objectstack/observability`](packages/observability) | Metrics, error reporting, and logging contracts with noop / console / OTLP exporters |
+| [`@objectstack/verify`](packages/verify) | Boot an app in-process and verify it through the real HTTP stack |
+
+#### Drivers
+
+| Package | Description |
+| :--- | :--- |
+| [`@objectstack/driver-memory`](packages/drivers/driver-memory) | In-memory driver (development, testing, reference implementation) |
+| [`@objectstack/driver-sql`](packages/drivers/driver-sql) | SQL driver — PostgreSQL, MySQL, SQLite via Knex |
+| [`@objectstack/driver-mongodb`](packages/drivers/driver-mongodb) | MongoDB driver over the official client |
+| [`@objectstack/driver-turso`](packages/drivers/driver-turso) | Turso / libSQL driver — edge-first SQLite with embedded replicas |
+| [`@objectstack/driver-sqlite-wasm`](packages/drivers/driver-sqlite-wasm) | WASM SQLite driver for browsers and WebContainers (StackBlitz) |
+
+#### Client
+
+| Package | Description |
+| :--- | :--- |
+| [`@objectstack/client`](packages/client) | Client SDK — CRUD, batch API, error handling |
+| [`@objectstack/client-react`](packages/client-react) | React hooks — `useQuery`, `useMutation`, `usePagination` |
+
+#### Plugins
+
+| Package | Description |
+| :--- | :--- |
+| [`@objectstack/plugin-hono-server`](packages/plugins/plugin-hono-server) | Hono-based HTTP server plugin |
+| [`@objectstack/hono`](packages/adapters/hono) | Hono adapter — Node.js, Bun, Deno, Cloudflare Workers |
+| [`@objectstack/mcp`](packages/mcp) | MCP server — exposes objects and AI tools over stdio and Streamable HTTP |
+| [`@objectstack/plugin-auth`](packages/plugins/plugin-auth) | Authentication and identity (better-auth) |
+| [`@objectstack/plugin-security`](packages/plugins/plugin-security) | RBAC, row-level and field-level security |
+| [`@objectstack/plugin-sharing`](packages/plugins/plugin-sharing) | Record-level sharing and `sharingModel` enforcement |
+| [`@objectstack/organizations`](packages/plugins/organizations) | Multi-organization row-level isolation |
+| [`@objectstack/plugin-approvals`](packages/plugins/plugin-approvals) | Multi-step approval engine |
+| [`@objectstack/plugin-audit`](packages/plugins/plugin-audit) | Audit log object and audit trail |
+| [`@objectstack/plugin-email`](packages/plugins/plugin-email) | Pluggable outbound email transport |
+| [`@objectstack/plugin-webhooks`](packages/plugins/plugin-webhooks) | Durable, cluster-aware outbound webhook delivery |
+| [`@objectstack/plugin-pinyin-search`](packages/plugins/plugin-pinyin-search) | Pinyin recall for CJK search |
+| [`@objectstack/plugin-dev`](packages/plugins/plugin-dev) | Zero-config local development assembly |
+| [`@objectstack/knowledge-memory`](packages/plugins/knowledge-memory) | In-memory knowledge adapter (dev / test) |
+| [`@objectstack/knowledge-ragflow`](packages/plugins/knowledge-ragflow) | RAGFlow knowledge adapter |
+| [`@objectstack/embedder-openai`](packages/plugins/embedder-openai) | OpenAI-compatible embedder (OpenAI, DashScope, Ollama, and any drop-in endpoint) |
+
+#### Connectors & triggers
+
+| Package | Description |
+| :--- | :--- |
+| [`@objectstack/connector-rest`](packages/connectors/connector-rest) | Generic REST connector for the automation engine |
+| [`@objectstack/connector-openapi`](packages/connectors/connector-openapi) | Connector actions generated from an OpenAPI document |
+| [`@objectstack/connector-mcp`](packages/connectors/connector-mcp) | Any MCP server's tools as connector actions |
+| [`@objectstack/connector-slack`](packages/connectors/connector-slack) | Slack Web API connector |
+| [`@objectstack/connector-imap`](packages/connectors/connector-imap) | Read-only IMAP session and mail account abstraction for the mailbox sync |
+| [`@objectstack/trigger-record-change`](packages/triggers/trigger-record-change) | Launch flows on insert / update / delete |
+| [`@objectstack/trigger-schedule`](packages/triggers/trigger-schedule) | Launch flows on a cron, interval, or one-off schedule |
+| [`@objectstack/trigger-api`](packages/triggers/trigger-api) | Inbound HTTP / webhook flow trigger with HMAC verification |
+
+#### Services
+
+| Package | Description |
+| :--- | :--- |
+| [`@objectstack/service-automation`](packages/services/service-automation) | Automation engine — DAG flows, triggers, workflow state machines |
+| [`@objectstack/service-analytics`](packages/services/service-analytics) | Aggregations, time series, funnels, dashboards |
+| [`@objectstack/service-realtime`](packages/services/service-realtime) | Real-time events and subscriptions |
+| [`@objectstack/service-job`](packages/services/service-job) | Cron and interval job scheduler |
+| [`@objectstack/service-queue`](packages/services/service-queue) | Background job queue — in-memory or durable DB-backed |
+| [`@objectstack/service-cache`](packages/services/service-cache) | Cache — in-memory and Redis |
+| [`@objectstack/service-cluster`](packages/services/service-cluster) | Cluster primitives — PubSub, Lock, KV, Counter |
+| [`@objectstack/service-cluster-redis`](packages/services/service-cluster-redis) | Redis driver for the cluster service |
+| [`@objectstack/service-storage`](packages/services/service-storage) | File storage — local filesystem and S3 |
+| [`@objectstack/service-datasource`](packages/services/service-datasource) | External-table federation and datasource lifecycle |
+| [`@objectstack/service-settings`](packages/services/service-settings) | Settings — manifest registry and K/V resolver (env > tenant > user) |
+| [`@objectstack/service-i18n`](packages/services/service-i18n) | Internationalization |
+| [`@objectstack/service-messaging`](packages/services/service-messaging) | Outbound notification dispatch across channels |
+| [`@objectstack/service-sms`](packages/services/service-sms) | SMS delivery (Aliyun, Twilio, log) |
+| [`@objectstack/service-knowledge`](packages/services/service-knowledge) | Knowledge / RAG orchestration over pluggable adapters |
+| [`@objectstack/service-package`](packages/services/service-package) | Package registry — publish, install, manage metadata packages |
+| [`@objectstack/cloud-connection`](packages/cloud-connection) | Runtime-side client for an ObjectStack cloud control plane |
+
+#### Tools & apps
+
+| Package | Description |
+| :--- | :--- |
+| [`@objectstack/cli`](packages/cli) | The `os` / `objectstack` CLI |
+| [`create-objectstack`](packages/create-objectstack) | Project scaffolder (`npm create objectstack`) |
+| [`@objectstack/console`](packages/console) | Prebuilt Console SPA, version-locked to this release; built from [`ui/apps/console`](ui/apps/console) in this repository |
+| [`@objectstack/studio`](packages/apps/studio) | Studio — the visual metadata builder app |
+| [`@objectstack/setup`](packages/apps/setup) | Setup — the platform administration app |
+| [`@objectstack/account`](packages/apps/account) | Account — sign in, organizations, connected apps |
+| [`@objectstack/docs`](apps/docs) | Documentation site (Fumadocs + Next.js) |
+
+#### Examples
+
+| Example | What it shows |
+| :--- | :--- |
+| [`examples/app-todo`](examples/app-todo) | The smallest app — objects, views, dashboards, flows |
+| [`examples/app-crm`](examples/app-crm) | A minimal CRM exercising the full metadata pipeline: objects → views → app → dashboard → hooks → flows → seed |
+| [`examples/app-showcase`](examples/app-showcase) | Kitchen sink — every metadata type, view type, chart type, and capability chain; what `pnpm dev` runs |
+| [`examples/app-multi-package`](examples/app-multi-package) | One release artifact carrying two packages that share a namespace |
+| [`examples/embed-objectql`](examples/embed-objectql) | ObjectQL as a plain library — no kernel, no plugins |
+| [HotCRM](https://github.com/objectstack-ai/hotcrm) | Full-featured enterprise CRM reference app (separate repo) |
+
+</details>
+
 ## Pull Request Process
 
 ### Before Submitting

LICENSING.md

@@ -1,19 +1,23 @@
 # Licensing
 
-ObjectStack Framework is licensed under the Apache License, Version 2.0.
+This repository is Apache-2.0, except `ui/` (the Console and `@object-ui/*`), which is MIT — both permissive.
+Everything outside `ui/` is licensed under the Apache License, Version 2.0
+([LICENSE](./LICENSE)); `ui/` is licensed under the MIT License
+([ui/LICENSE](./ui/LICENSE)).
 
 This repository contains everything you need to **build, run, and self-host
-your own applications** under that license: the protocol (`@objectstack/spec`),
-kernel, SDK, CLI, production runtime (`os start`), and the official Docker
-image definition ([`docker/`](./docker), published as
+your own applications** under those licenses: the protocol (`@objectstack/spec`),
+kernel, SDK, CLI, production runtime (`os start`), the Console (`ui/`), and the
+official Docker image definition ([`docker/`](./docker), published as
 `ghcr.io/objectstack-ai/objectstack`). There is no feature gate between
 development and production in this repository.
 
-**ObjectOS** — the official runtime environment for end-user organizations,
-delivered as **ObjectOS Cloud** (managed) and **ObjectOS Enterprise**
-(self-managed) — is a separate commercial product and is not part of this
-repository. Its editions, official cloud services, and marketplace commercial
-terms are governed by their own agreements. See
-[docs.objectos.ai](https://docs.objectos.ai).
+**ObjectOS** is the runtime's product name, in three editions. **ObjectOS
+Community** is what this repository ships, under the licenses above.
+**ObjectOS Cloud** (managed) and **ObjectOS Enterprise** (self-managed) are
+commercial editions and are not part of this repository; they, the official
+cloud services, and marketplace commercial terms are governed by their own
+agreements. See [docs.objectos.ai](https://docs.objectos.ai).
 
-The full Apache 2.0 license text is available in [LICENSE](./LICENSE).
+The full Apache 2.0 license text is available in [LICENSE](./LICENSE), and the
+MIT license text for `ui/` in [ui/LICENSE](./ui/LICENSE).