docs: stop advertising src/agents and src/cubes, guard the tree in CI

#512 deleted `src/agents/` when the AI surface went skills-only, but seven
maintainer docs kept printing `src/agents/*.agent.ts` in their tree
diagrams and registration tables. `code_examples.md` was the worst of it:
after registering a skill it told the author to "add its name to an agent
in `src/agents/*.agent.ts`" — an instruction that cannot be followed.
`src/cubes/` had the same shape, dropped in favour of datasets (ADR-0021,
noted in objectstack.config.ts) and still drawn in two trees.

Nothing checked, because a path in prose is just prose. That is the same
failure mode as #493 one layer out: metadata validation sees a
well-formed string and stops, so the reference rots silently and the next
reader — human or agent — is sent somewhere that does not exist.

- README.md, AGENTS.md, docs/README.md, docs/STATUS.md,
  docs/ARCHITECTURE.md, docs/developers/code_examples.md: drop the agent
  and cube directories; README picks up `src/datasets/` (the layer that
  actually replaced cubes) and its flow count goes 20 → 23; AGENTS.md's
  `*.action.ts` becomes `*.actions.ts`, the real suffix.
- code_examples.md: drop the skill `permissions: [...]` key — SkillSchema
  has no such field and strips it silently (#511) — and fill the gap the
  deletions leave. The example now says which two sources a `tools` name
  can resolve to (platform data tools, or `action_<name>` from an
  `ai.exposed` Action with a headless path), why `defineTool` is not a
  third one, that reasoning belongs in `instructions` (ADR-0109), and
  where the guard lives.
- ARCHITECTURE.md: same note, plus the `case_triage` skill its table had
  been missing.

Adds a repo-tree guard to test/docs-drift.test.ts — every `src/<dir>/` a
maintainer doc names must resolve on disk, with `docs/archive/` excluded
as a historical record. It earned its place immediately by failing on a
stray `no src/agents/` parenthetical in this change's own first pass.

155 tests (+9), typecheck, validate and build pass; the 2 remaining
validate warnings are the pre-existing campaign_enrollment ones.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y9STuduWbrAwcgviziaV4e

Author: claude

.changeset/docs-retired-agent-cube-directories.md

@@ -0,0 +1,24 @@
+---
+'hotcrm': patch
+---
+
+Stop documenting directories that no longer exist, and guard the class. `#512`
+deleted `src/agents/` when the AI surface went skills-only, but seven maintainer
+docs kept printing `src/agents/*.agent.ts` in their tree diagrams and
+registration tables — `code_examples.md` still told authors to "add its name to
+an agent in `src/agents/*.agent.ts`" after registering a skill. `src/cubes/` had
+the same shape: dropped in favour of datasets (ADR-0021, noted in
+`objectstack.config.ts`), still drawn in two trees. Also removes the skill
+`permissions: [...]` key from the worked example — `SkillSchema` has no such
+field and silently strips it (#511) — and corrects a stale flow count (20 → 23)
+and the `*.action.ts` suffix (the convention is `*.actions.ts`).
+
+Fills the gap left behind: the skill example now states which two sources a
+`tools` name can resolve to (platform data tools, or `action_<name>` from an
+`ai.exposed` Action), why `defineTool` is not a third one, and where the guard
+lives. `ARCHITECTURE.md` gains the same note plus the missing `case_triage`
+skill.
+
+Adds a repo-tree guard to `test/docs-drift.test.ts`: every `src/<dir>/` path a
+maintainer doc names must exist on disk (`docs/archive/` excluded — it is a
+historical record). It caught a stray reference in this change's own first pass.

AGENTS.md

@@ -35,9 +35,9 @@ hotcrm/
 │   ├── 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
+│   ├── actions/            # UI actions + AI-callable tools (*.actions.ts)
+│   ├── dashboards/ reports/ datasets/          # Analytics metadata
+│   ├── skills/             # AI skill metadata (*.skill.ts) — skills-only surface
 │   ├── profiles/ sharing/  # Permission sets, role hierarchy, sharing rules
 │   ├── translations/       # Locale bundles (en / zh-CN / es-ES / ja-JP)
 │   └── data/               # Seed data (defineDataset)

README.md

@@ -126,11 +126,10 @@ hotcrm/
 ├── src/
 │   ├── objects/                  # *.object.ts — data model (15 objects)
 │   ├── actions/                  # *.actions.ts — server actions + AI tools (13)
-│   ├── flows/                    # *.flow.ts — visual flows (20): screen, record-change & scheduled
+│   ├── flows/                    # *.flow.ts — visual flows (23): screen, record-change & scheduled
 │   ├── hooks/                    # hook registry barrel
-│   ├── agents/                   # *.agent.ts — AI copilots (2)
-│   ├── skills/                   # *.skill.ts — AI skills (6)
-│   ├── cubes/                    # *.cube.ts — analytics cubes
+│   ├── skills/                   # *.skill.ts — AI skills (6) — skills-only surface, no agents
+│   ├── datasets/                 # *.dataset.ts — analytics semantic layer (8)
 │   ├── dashboards/, reports/     # analytics UI
 │   ├── pages/, views/, apps/     # UI definitions
 │   ├── profiles/, sharing/       # security

docs/ARCHITECTURE.md

@@ -45,10 +45,9 @@ Runtime capabilities are declared in `requires`: `ai`, `automation`, `triggers`,
 | Lifecycle hooks | `src/objects/*.hook.ts` via `src/hooks/index.ts` | `hooks` |
 | UI actions | `src/actions/*.actions.ts` | `actions` |
 | Automation | `src/flows/*.flow.ts` | `flows` |
-| AI agents | `src/agents/*.agent.ts` | `agents` |
 | AI skills | `src/skills/*.skill.ts` | `skills` |
 | Apps, views, pages | `src/apps/`, `src/views/`, `src/pages/` | `apps`, `views`, `pages` |
-| Analytics | `src/cubes/`, `src/dashboards/`, `src/reports/` | `analyticsCubes`, `dashboards`, `reports` |
+| Analytics | `src/datasets/`, `src/dashboards/`, `src/reports/` | `datasets`, `dashboards`, `reports` |
 | Security | `src/profiles/`, `src/sharing/` | `permissions`, `sharingRules`, `roles` |
 | i18n | `src/translations/` | `translations`, `i18n` |
 | Demo data | `src/data/` | `data` |
@@ -127,15 +126,24 @@ The UI is metadata-driven. Object field definitions, views, pages, actions, perm
 
 ## AI
 
-AI is modeled as ObjectStack metadata:
+AI is modeled as ObjectStack metadata. The surface is **skills-only**: the two
+`*.agent.ts` copilots were retired in [#512](https://github.com/objectstack-ai/hotcrm/pull/512),
+because ADR-0063 §2 closed agent records to third parties and the runtime
+refuses non-platform ones. The capability lives in the skills, which attach to
+the platform assistant by surface affinity.
 
 | Layer | Files | Examples |
 | --- | --- | --- |
-| Agents | `src/agents/*.agent.ts` | `sales_copilot`, `service_copilot` |
-| Skills | `src/skills/*.skill.ts` | `live_data`, `lead_qualification`, `email_drafting`, `revenue_forecasting`, `customer_360` |
+| Skills | `src/skills/*.skill.ts` | `live_data`, `lead_qualification`, `email_drafting`, `revenue_forecasting`, `case_triage`, `customer_360` |
 | Actions and flows | `src/actions/`, `src/flows/` | lead conversion, case triage, alerts |
 
-The Sales Copilot instructions explicitly require live schema inspection before answering record questions, because admins can change metadata over time.
+Skills declare no bespoke tools (ADR-0109). They compose the platform's data
+tools with the `action_<name>` tools the runtime materialises from Actions that
+opt in via `ai.exposed` (ADR-0011) — every name a skill declares must resolve to
+one of those, which `test/skills-integrity.test.ts` enforces.
+
+The `live_data` skill explicitly requires live schema inspection before
+answering record questions, because admins can change metadata over time.
 
 ## Security
 

docs/README.md

@@ -37,8 +37,7 @@ hotcrm/
 │   ├── objects/        # ObjectSchema.create metadata, object lifecycle hooks
 │   ├── actions/        # UI actions and AI-callable action bodies
 │   ├── flows/          # ObjectStack automation flows
-│   ├── agents/         # AI agent definitions
-│   ├── skills/         # AI skills used by agents
+│   ├── skills/         # AI skill definitions (skills-only surface)
 │   ├── dashboards/     # Dashboard metadata
 │   ├── reports/        # Report metadata
 │   ├── views/, pages/  # App UI metadata

docs/STATUS.md

@@ -56,8 +56,7 @@ pnpm verify
 | Object hooks | `src/objects/*.hook.ts`, collected by `src/hooks/index.ts` |
 | Actions | `src/actions/*.actions.ts` |
 | Flows | `src/flows/*.flow.ts` |
-| Agents | `src/agents/*.agent.ts` |
-| Skills | `src/skills/*.skill.ts` |
+| Skills | `src/skills/*.skill.ts` (skills-only AI surface since #512 — the agent directory is gone) |
 | Views and pages | `src/views/`, `src/pages/` |
 | Dashboards and reports | `src/dashboards/`, `src/reports/` |
 | Security | `src/profiles/`, `src/sharing/` |

docs/developers/code_examples.md

@@ -2,7 +2,7 @@
 
 > Examples that match the current single-app HotCRM repository.
 
-HotCRM metadata is registered from `src/` through [`objectstack.config.ts`](../../objectstack.config.ts). File names use the ObjectStack suffix convention: `.object.ts`, `.hook.ts`, `.actions.ts`, `.flow.ts`, `.agent.ts`, `.skill.ts`, `.view.ts`, `.page.ts`, `.dashboard.ts`, and `.report.ts`.
+HotCRM metadata is registered from `src/` through [`objectstack.config.ts`](../../objectstack.config.ts). File names use the ObjectStack suffix convention: `.object.ts`, `.hook.ts`, `.actions.ts`, `.flow.ts`, `.skill.ts`, `.view.ts`, `.page.ts`, `.dashboard.ts`, and `.report.ts`.
 
 ## Define An Object
 
@@ -188,7 +188,7 @@ export const WarrantyExpirationFlow: Flow = {
 
 Export flows from `src/flows/index.ts`. Record-change flows require the `triggers` capability, which is already declared in `objectstack.config.ts`.
 
-## Add An Agent Skill
+## Add An AI Skill
 
 File: `src/skills/example.skill.ts`
 
@@ -204,11 +204,34 @@ summarize status, identify expired or soon-expiring warranties, and
 recommend the next action.`,
   tools: ['describe_object', 'query_records'],
   triggerPhrases: ['summarize warranties', 'warranty risk'],
-  permissions: ['crm:account:read'],
 });
 ```
 
-Register the skill in `src/skills/index.ts`, then add its name to an agent in `src/agents/*.agent.ts` if the agent should use it.
+Register the skill in `src/skills/index.ts`. There is no agent to attach it to —
+the AI surface is skills-only ([#512](https://github.com/objectstack-ai/hotcrm/pull/512)),
+and a skill binds to the platform assistant through its `surface` affinity.
+
+**Every name in `tools` must resolve to something that actually runs.** The
+runtime silently drops a tool it cannot resolve, so an invented name leaves the
+model with instructions describing a capability it does not have — the defect
+[#493](https://github.com/objectstack-ai/hotcrm/issues/493) catalogued. Two
+sources resolve, and only two:
+
+- **Platform data tools** — `describe_object`, `list_objects`, `query_records`,
+  `get_record`, `aggregate_data`.
+- **`action_<name>`** — materialised from an Action that opts in with
+  `ai: { exposed: true, description }` (ADR-0011, default off) *and* has a
+  headless path. See `ConvertLeadAction` in `src/actions/lead.actions.ts`.
+
+Authoring a `defineTool` record does **not** create a third source: `ToolSchema`
+is a read-only projection for Studio discovery with no `implementation` field
+and no executor. Reasoning — scoring, drafting, forecasting — belongs in
+`instructions`, not in a tool (ADR-0109). `test/skills-integrity.test.ts`
+enforces all of this at PR time.
+
+Note there is no `permissions` key on a skill — `SkillSchema` has no such field,
+so one is silently stripped ([#511](https://github.com/objectstack-ai/hotcrm/pull/511)).
+Gate access on the Actions the skill calls instead.
 
 ## Common Registration Points
 
@@ -218,7 +241,6 @@ Register the skill in `src/skills/index.ts`, then add its name to an agent in `s
 | Hook | `src/objects/` | `src/hooks/index.ts` |
 | Action | `src/actions/` | `src/actions/index.ts` |
 | Flow | `src/flows/` | `src/flows/index.ts` |
-| Agent | `src/agents/` | `src/agents/index.ts` |
 | Skill | `src/skills/` | `src/skills/index.ts` |
 | View | `src/views/` | `src/views/index.ts` |
 | Page | `src/pages/` | `src/pages/index.ts` |

test/docs-drift.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect } from 'vitest';
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 /**
@@ -143,3 +143,45 @@ describe('package docs do not drift from the flows they document', () => {
     });
   }
 });
+
+/**
+ * Repo-tree drift — a doc must not advertise a directory that is gone.
+ *
+ * `src/agents/` outlived its deletion by three PRs. #512 removed the two
+ * copilots and the whole directory, but seven maintainer docs kept printing
+ * `src/agents/*.agent.ts` in their tree diagrams and registration tables, so
+ * the next reader (human or agent) was told to put a file somewhere that does
+ * not exist. `src/cubes/` had the same shape: dropped in favour of datasets
+ * (ADR-0021, see the note in objectstack.config.ts), still drawn in two trees.
+ *
+ * Nothing checked, because a path in prose is just prose. This walks the
+ * maintainer docs, pulls every `src/<dir>/` they mention, and resolves it
+ * against the real tree. `docs/archive/` is deliberately excluded — it is a
+ * historical record and is allowed to describe a repo that no longer exists.
+ */
+const TREE_DOCS = [
+  'README.md',
+  'AGENTS.md',
+  'docs/README.md',
+  'docs/STATUS.md',
+  'docs/ARCHITECTURE.md',
+  'docs/MAINTENANCE.md',
+  'docs/DEPLOYMENT.md',
+  'docs/developers/code_examples.md',
+  'docs/developers/api_reference.md',
+];
+
+describe('maintainer docs do not point at directories that no longer exist', () => {
+  for (const docFile of TREE_DOCS) {
+    it(`${docFile}: every src/<dir>/ it names exists`, () => {
+      const text = readFileSync(join(docFile), 'utf8');
+      const named = new Set([...text.matchAll(/\bsrc\/([a-z][a-z0-9_]*)\//g)].map((m) => m[1]));
+      const missing = [...named].filter((dir) => !existsSync(join('src', dir)));
+      expect(
+        missing,
+        `${docFile} advertises src/ directories that do not exist: ${missing.join(', ')}. ` +
+          'Delete the reference (or restore the directory) — a path in prose is still a promise.',
+      ).toEqual([]);
+    });
+  }
+});