docs: reconcile AGENTS.md to flat src/ + add maintenance & requirements management (#405)

- AGENTS.md: replace the retired packages/* monorepo description with the real
  single-app flat src/{type}/ layout; add *.flow.ts to the file-suffix protocol;
  fix stale example paths and the dependencies note
- docs/MAINTENANCE.md: platform-upgrade + seed-staleness + version-alignment playbook
- docs/requirements/: file-based, AI-native requirements log mapping a raw
  customer requirement to a standard-product disposition (A/B/C/D), with the
  overlay-vs-core seam; includes TEMPLATE.md and an illustrative REQ-0001
- wire the new docs into docs/README.md nav and .github/tasks/new-feature.md

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

.github/tasks/new-feature.md

@@ -2,14 +2,20 @@
 
 **Goal**: Add a functional vertical slice (Object + Logic + UI).
 
+**Start from the requirement**: this feature should trace to a record under
+[`docs/requirements/`](../../docs/requirements/README.md). Read its **disposition**
+first — `B` (standard enhancement) lands in core `src/{type}/`; `C`
+(customer-specific) belongs in an overlay/extension package, **not** in HotCRM core.
+
 **Prompt**:
 ```markdown
-I want to add a `[FEATURE_NAME]` feature to the `[PACKAGE_NAME]` package.
+I want to add a `[FEATURE_NAME]` feature to HotCRM (single app, namespace `crm`),
+implementing requirement `REQ-[NNNN]`.
 
 **Requirements**:
-1. **Model**: Create `[OBJECT_NAME].object.ts` with fields: [LIST_FIELDS].
-2. **Logic**: Create `[OBJECT_NAME].hook.ts` to implement: [DESCRIBE_LOGIC].
-3. **UI**: Create `[OBJECT_NAME].page.ts` for a standard record layout.
+1. **Model**: Create `src/objects/[OBJECT_NAME].object.ts` with fields: [LIST_FIELDS]. Use the `crm_` prefix.
+2. **Logic**: Create `src/objects/[OBJECT_NAME].hook.ts` to implement: [DESCRIBE_LOGIC].
+3. **UI**: Create `src/views/[OBJECT_NAME].view.ts` and `src/pages/[OBJECT_NAME].page.ts` for a standard record layout.
 
 Please follow the strictly typed metadata standards in `.github/instructions/metadata.md`.
 ```

AGENTS.md

@@ -5,7 +5,7 @@ Enterprise CRM built on the **@objectstack/runtime** engine. Tool-specific files
 (e.g. `.github/copilot-instructions.md`) point here.
 
 You are an expert developer working on HotCRM, delivering business capabilities
-through modular packages on top of the ObjectStack platform.
+as metadata on top of the ObjectStack platform.
 
 ## 🗣️ 沟通语言 / Communication Language
 
@@ -18,25 +18,37 @@ commit messages, PR titles/bodies, and code comments in English.
 
 ## 🏗️ Project Architecture
 
-HotCRM follows a **Plugin-Based Monorepo** structure:
+HotCRM is a **single ObjectStack marketplace app**, not a multi-package monorepo.
+The source of truth is `objectstack.config.ts`, which registers all metadata from a
+flat `src/` tree organised **by metadata type** (not by business package).
 
 - **Engine**: We DO NOT build the core engine. We use `@objectstack/runtime` as the platform dependency.
-- **Business Packages** (`packages/*`): We develop independent functional modules here.
-- **Apps** (`apps/*`): Deployable applications (Documentation, Admin Portal).
+- **Metadata** (`src/{type}/`): All business capability lives here as typed metadata files.
+- **Product docs** (`content/docs/`): User/admin/marketplace documentation (Fumadocs).
+- **Internal docs** (`docs/`): Architecture, status, release, and maintenance notes.
 
-**Directory Structure**:
+**Directory Structure** (see `docs/README.md` for the full map):
 ```
 hotcrm/
-├── packages/               # Business Capabilities (Plugins)
-│   ├── crm/               # Sales Cloud (Account, Opportunity)
-│   ├── finance/           # Revenue Cloud (Contract, Invoice)
-│   ├── products/          # CPQ Product Catalog
-│   └── ...
-│
-└── apps/
-    └── docs/              # Official Documentation
+├── objectstack.config.ts   # App manifest — registers metadata from src/
+├── src/
+│   ├── objects/            # *.object.ts schemas + *.hook.ts lifecycle hooks
+│   ├── views/  pages/      # App UI metadata (*.view.ts / *.page.ts)
+│   ├── flows/              # Automation (*.flow.ts)
+│   ├── actions/            # UI actions + AI-callable tools (*.action.ts)
+│   ├── dashboards/ reports/ datasets/ cubes/   # Analytics metadata
+│   ├── agents/ skills/     # AI agent + skill metadata
+│   ├── profiles/ sharing/  # Permission sets, role hierarchy, sharing rules
+│   ├── translations/       # Locale bundles (en / zh-CN / es-ES / ja-JP)
+│   └── data/               # Seed data (defineDataset)
+├── content/docs/           # Product documentation site content
+└── docs/                   # Internal maintainer documentation
 ```
 
+> The retired multi-package (`packages/*`) direction is archived under
+> `docs/archive/`. Do NOT create `packages/<x>/src/` paths — everything lives in the
+> flat `src/{type}/` tree above.
+
 ## 💻 Tech Stack & Protocol
 
 1.  **Metadata-First (`*object.ts`)**:
@@ -60,12 +72,12 @@ hotcrm/
 When asked to implement a feature, you MUST follow this **Thinking Process**:
 
 ### Phase 1: Architecture & Planning
-1.  **Analyze**: Identify the Business Package (e.g., `packages/hr`) and Dependencies.
+1.  **Analyze**: Identify the domain area (e.g., sales, service, marketing) and the metadata it touches.
 2.  **Schema Design**: List all necessary Objects, Fields, and Relationships.
 3.  **File Inventory**: List exact file paths to be created.
-    *   `src/candidate.object.ts` (Data)
-    *   `src/candidate.workflow.ts` (Automation)
-    *   `src/candidate.page.ts` (UI)
+    *   `src/objects/candidate.object.ts` (Data)
+    *   `src/flows/candidate.flow.ts` (Automation)
+    *   `src/pages/candidate.page.ts` (UI)
 
 ### Phase 2: Implementation (Iterative)
 1.  **Metadata First**: Create `*.object.ts` files first. They are the source of truth.
@@ -81,12 +93,13 @@ After generating code, ask yourself:
 
 ## 📝 Coding Standards (The "File Suffix Protocol")
 
-We enforce strict file naming to separate concerns. Files should be located in `packages/{package_name}/src/`.
+We enforce strict file naming to separate concerns. Files live under `src/{type}/`, grouped by metadata type (e.g. `src/objects/`, `src/flows/`, `src/views/`).
 
 ### Core File Types
 - `*.object.ts`: Data Model (Schema) — validated with `ObjectSchema.parse()`
 - `*.hook.ts`: Server-side Business Logic (Triggers)
 - `*.action.ts`: API Endpoints & AI Tools
+- `*.flow.ts`: Automation Flows — typed as `Automation.Flow` from `@objectstack/spec/automation`
 - `*.page.ts`: UI Page Layouts — validated with `PageSchema` from `@objectstack/spec/ui`
 - `*.view.ts`: List View Configurations — validated with `ViewSchema` from `@objectstack/spec/ui`
 
@@ -130,19 +143,19 @@ Use the most specific `Field` type available from `@objectstack/spec/data`:
 
 ## 🚀 Development Workflow
 
-1.  **Define Object**: Create `packages/{pkg}/src/{entity}.object.ts`.
-2.  **Add Logic**: Create `packages/{pkg}/src/{entity}.hook.ts`.
-3.  **Expose Action**: Create `packages/{pkg}/src/{action}.action.ts` if external API/AI needed.
-4.  **Config UI**: Create `packages/{pkg}/src/{entity}.page.ts`.
+1.  **Define Object**: Create `src/objects/{entity}.object.ts`.
+2.  **Add Logic**: Create `src/objects/{entity}.hook.ts`.
+3.  **Expose Action**: Create `src/actions/{action}.action.ts` if external API/AI needed.
+4.  **Config UI**: Create `src/views/{entity}.view.ts` and `src/pages/{entity}.page.ts`.
 
 ## ⚠️ Constraint Checklist
 
 - **Object Naming**: All HotCRM business objects MUST be prefixed with `crm_` (e.g., `crm_account`, `crm_opportunity`, `crm_case`, `crm_lead`, `crm_campaign`, `crm_contact`, `crm_contract`, `crm_product`, `crm_quote`, `crm_quote_line_item`, `crm_opportunity_line_item`, `crm_task`, `crm_campaign_member`, `crm_knowledge_article`, `crm_forecast`). All references — `reference_to`, `lookup`, `masterDetail`, cube `sql`, view `data.object`, hook `object`, navigation `objectName`, action `objectName`, dashboard `object` — MUST use the prefixed form. Platform objects keep their existing `sys_*` prefix.
 - **i18n**: Every new object must have entries in all 4 locale files (`src/translations/{en,zh-CN,es-ES,ja-JP}.ts`) — label, pluralLabel, all field labels + option labels, view labels, navigation labels. No new feature ships without all 4 locales.
-- **Docs**: Every new object/feature requires user-facing documentation under `content/docs/{sales|service|marketing|...}/` written for business users + admins (not developers).
+- **Docs**: Every new object/feature requires user-facing documentation under `content/docs/` (e.g. `getting-started/`, `guides/`, `marketing/`, `analytics/`, `administration/`) written for business users + admins (not developers).
 - **Documentation**: All documentation MUST be in English.
 - **No Engine Code**: Do not try to modify the core runtime code. Focus on the *usage* of the runtime.
-- **Dependencies**: HotCRM packages should depend on `@objectstack/runtime` (as peerDependency) and other sibling packages if structure allows.
+- **Dependencies**: HotCRM depends on the published `@objectstack/*` packages (runtime, spec, drivers, services) declared in `package.json`. Keep `specVersion` in `objectstack.manifest.json` aligned with the installed `@objectstack/spec`.
 - **Tone**: Act as a Senior 10x Engineer. Be concise, professional, and technically accurate.
 
 > **Naming note (ADR-0048):** the `crm_` prefix above is a deliberate HotCRM
@@ -162,7 +175,7 @@ The following are **NOT** in HotCRM's scope — they are platform-level features
 - **Low-level services**: database engine, auth (OAuth/SAML/SSO), multi-tenancy, encryption, API gateway, caching, message queue, file storage.
 - **Dev tools**: schema migration, CLI scaffolding, metadata deployment pipeline, VCS integration, IDE extensions.
 
-**Focus Area**: HotCRM focuses exclusively on **business domain packages** (CRM, Finance, HR, Marketing, Products, Support) and their **business logic, data models, and AI capabilities**.
+**Focus Area**: HotCRM focuses exclusively on **business domains** (CRM, Finance, HR, Marketing, Products, Support) and their **business logic, data models, and AI capabilities** — authored as metadata in `src/`.
 
 ---
 

docs/MAINTENANCE.md

@@ -0,0 +1,109 @@
+# HotCRM Maintenance & Upgrade Playbook
+
+> Scope: how to keep this single ObjectStack marketplace app healthy over time —
+> the everyday change loop, platform (`@objectstack/*`) upgrades, seed-data
+> verification, and version alignment.
+>
+> HotCRM is a **consumer** of the ObjectStack platform, not the platform itself.
+> It therefore does **not** keep an ADR log (those live in the `framework` repo).
+> Its decisions are business/domain decisions captured as metadata in `src/`,
+> plus a changeset per change. See [README.md](README.md) for the doc map.
+
+## 1. How HotCRM is managed
+
+There is no separate "project management" system — the repo files **are** the
+management surface. Know which file owns which fact:
+
+| Concern | Source of truth |
+| --- | --- |
+| Conventions for humans + AI agents | [`AGENTS.md`](../AGENTS.md) |
+| Customer requirements → product disposition | [`docs/requirements/`](requirements/README.md) |
+| App identity (id, namespace, version) | [`objectstack.config.ts`](../objectstack.config.ts) + [`objectstack.manifest.json`](../objectstack.manifest.json) |
+| What metadata exists (live counts) | [`docs/STATUS.md`](STATUS.md) — regenerated from `pnpm validate` |
+| How it ships | [`docs/RELEASE_STRATEGY.md`](RELEASE_STRATEGY.md) |
+| What changed, per release | [`CHANGELOG.md`](../CHANGELOG.md) + `.changeset/` |
+| Architecture overview | [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) |
+| User/admin docs | [`content/docs/`](../content/docs/) |
+
+## 2. Everyday change loop (per PR)
+
+1. Author metadata under the correct `src/{type}/` folder (see `AGENTS.md`).
+2. Keep all 4 locale bundles in sync (`src/translations/{en,zh-CN,es-ES,ja-JP}.ts`).
+3. Add the matching user doc under `content/docs/` if behaviour changed.
+4. Add a changeset describing the change.
+5. Run the full gate and make sure it is green:
+
+   ```bash
+   pnpm verify   # = validate && typecheck && build && test
+   ```
+
+6. Open the PR. **Merge only after remote CI is fully green** — never `--auto`
+   ahead of CI, and never edit on a shared `main` checkout (use a worktree).
+
+## 3. Platform upgrade checklist (`@objectstack/*` bump)
+
+This is the single riskiest routine operation, because a platform contract change
+can silently invalidate existing metadata or **seed data** (see §4). Treat every
+`@objectstack/*` version bump as a verification event, not a dependency tweak.
+
+1. Bump all `@objectstack/*` deps in [`package.json`](../package.json) together —
+   they are released in lockstep, so keep them on one version line.
+2. Update `specVersion` in [`objectstack.manifest.json`](../objectstack.manifest.json)
+   to match the installed `@objectstack/spec` (e.g. `^9.11.0`).
+3. `pnpm install`.
+4. `pnpm verify`. Validation failures here are usually metadata that a new
+   platform contract just started enforcing — fix the metadata, do not pin back.
+5. **Reset and reseed**, then smoke-test in the Console (see §4):
+
+   ```bash
+   pnpm demo:reset   # wipes .objectstack/data, rebuilds; seeds reload on first boot
+   pnpm dev          # then open the Console and eyeball the seeded app
+   ```
+
+6. If `better-sqlite3` floods `NODE_MODULE_VERSION ... requires ...` on boot, the
+   native binary was built for a different Node ABI — `pnpm rebuild better-sqlite3`
+   and restart. This is an environment issue, not an app change.
+7. Note the new platform version in `CHANGELOG.md`.
+
+## 4. Seed-data staleness — the #1 HotCRM pitfall
+
+Stale seed data is the most common cause of "Studio shows a red
+'metadata is invalid' banner" or "the home page lists pending issues." It is
+**almost always the seed, not a designer bug**: a platform contract changed
+(a validation rule was retired, a dashboard now requires a `dataset` + values),
+and the fixtures in `src/data/` were never updated to match.
+
+After any platform upgrade, or whenever Studio shows validation banners:
+
+1. `pnpm validate` — confirm the **metadata** itself is clean.
+2. `pnpm demo:reset && pnpm dev` — reseed from a clean DB.
+3. Open the Console and visually verify the seeded records, dashboards, and
+   views render. For dashboards, **wait for the lazy-loaded chart bundle** before
+   judging an empty card (see `AGENTS.md` → "Verifying UI in the browser").
+4. If a banner persists, fix the offending fixture in `src/data/`, not the
+   designer or the platform.
+
+## 5. Releasing
+
+HotCRM ships as **one** app package (`hotcrm` / `app.objectstack.hotcrm`). Before
+publishing, keep the version aligned across all four places:
+
+- `package.json` `version`
+- `objectstack.config.ts` manifest `version`
+- `CHANGELOG.md`
+- the marketplace publish note
+
+Full procedure (build artifact, dry-run, publish) lives in
+[`RELEASE_STRATEGY.md`](RELEASE_STRATEGY.md). Do not duplicate it here.
+
+> **Keep `STATUS.md` honest.** It is a snapshot, not live — regenerate its counts
+> and version from `pnpm validate` whenever they drift from `package.json`.
+
+## 6. When HotCRM actually needs a design doc
+
+Rarely. HotCRM does not use the platform's ADR-NNNN system. Reach for a short
+design note (placed in `docs/`, archived to `docs/archive/` when superseded) only
+when a decision is **cross-cutting and hard to reverse** and a future maintainer
+would need the "why" — e.g. the explicit `crm_` prefix convention already
+recorded in `AGENTS.md`. Routine "added an object / view / flow" work needs a
+changeset, not a design doc.

docs/README.md

@@ -13,6 +13,8 @@ HotCRM also has product-facing documentation under [`content/docs/`](../content/
 | Runtime and metadata architecture | [ARCHITECTURE.md](ARCHITECTURE.md) |
 | Local, artifact, and marketplace deployment | [DEPLOYMENT.md](DEPLOYMENT.md) |
 | Versioning and distribution | [RELEASE_STRATEGY.md](RELEASE_STRATEGY.md) |
+| Upgrade, seeding, and version alignment | [MAINTENANCE.md](MAINTENANCE.md) |
+| Customer requirements and product disposition | [requirements/README.md](requirements/README.md) |
 | Object field reference | [developers/api_reference.md](developers/api_reference.md) |
 | ObjectStack code examples | [developers/code_examples.md](developers/code_examples.md) |
 

docs/requirements/0001-agency-tier-lead-tagging.md

@@ -0,0 +1,51 @@
+# REQ-0001: Auto-tag leads by the customer's agency-tier hierarchy
+
+> **Illustrative example** — a worked sample showing the record format and the
+> disposition framework. Replace or delete it when the first real requirement lands.
+
+- **Status**: Triaged
+- **Source**: Example customer — mid-market manufacturer
+- **Raised**: 2026-06-21
+- **Disposition**: C customer-overlay
+- **Traceability**: (example) overlay package `hotcrm-ext-acme` — not yet built
+
+## Raw requirement (verbatim)
+
+> 我们所有线索都来自代理商，代理商分 8 个等级（S/A/B/C/D/E/F/观察）。线索进来要按
+> 来源代理商的等级自动打标；S/A 级线索自动分配给大客户销售组，其它按区域轮询。
+
+## Standard product analysis
+
+HotCRM core has `crm_lead` with owner assignment driven by a routing flow
+(`src/flows/*`). It has **no** concept of an "agency tier" — that 8-level taxonomy
+is **this customer's partner-org structure**, not a general CRM primitive. Core
+already supports region / round-robin routing.
+
+## Disposition & rationale
+
+**C — customer-specific.** The 8-tier agency taxonomy and the S/A → key-account
+routing rule encode one customer's go-to-market structure. Baking an 8-level enum
+and a bespoke routing branch into core `crm_lead` would impose one customer's
+model on every other install.
+
+**Re-triage trigger → B:** if multiple customers ask for configurable
+lead-tiering, promote a *generic* `lead_tier` picklist + a configurable routing
+rule into core, and retire this overlay.
+
+## Product response
+
+Author a customer overlay / extension package on top of HotCRM — do **not** edit core:
+
+- Extend `crm_lead` with an overlay field `agency_tier` (select) via the
+  customization overlay (framework ADR-0005), not a core schema edit.
+- Add an overlay flow that sets `agency_tier` from the source agency and routes
+  S/A tiers to the key-account group.
+- Ship it as its own `packageId` so it coexists with HotCRM (framework ADR-0048)
+  and leaves base metadata protected (framework ADR-0010).
+
+## Acceptance
+
+In a HotCRM instance with the overlay installed: importing a lead from an S-tier
+agency sets `agency_tier = S` and assigns the key-account group; a C-tier lead
+falls through to regional round-robin. Core HotCRM (without the overlay) is
+unchanged.