#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

…real

The allowlist added in #557 guessed the platform tool set from what the
`@objectstack/mcp@16.1.0` bridge happens to register, and got it wrong in
both directions:

- It omitted `search_knowledge`, so the guard would have FAILED a
  legitimate reference. The tool is real — it is in
  `PLATFORM_PROVIDED_TOOL_NAMES`, and 16.1.0 documented it all along at
  `spec/src/ai/knowledge-source.zod.ts:114` ("Whether `search_knowledge`
  may expose this source to AI agents"). One grep for that name would
  have caught it; the same absent-from-node_modules inference was
  applied to `visualize_data` and came out the other way.
- It reasoned about deliberately excluding `create_record` /
  `update_record` / `delete_record`. Those are MCP-bridge tools and are
  not in the platform registry at all, so there was nothing to exclude.

The list is now transcribed verbatim from `PLATFORM_PROVIDED_TOOL_NAMES`
in `@objectstack/spec@17.0.0-rc.0` — all 30 entries, diffed equal to the
upstream set — carrying instructions to delete the literal and import it
on the 17.0 upgrade. A hand-copied registry is the drift risk this file
exists to catch, one level up; it is a stopgap for 16.1.0, which exposes
no such export.

Cross-checked against upstream's own `ai-skill-tool-unresolved` rule,
which ships in `@objectstack/lint@17.0.0-rc.0` (objectstack#3820). Both
give identical verdicts on seven probes: `search_knowledge`,
`query_data`, `todo_write` and `action_convert_lead` accepted;
`action_escalate_case` (not `ai.exposed`), `search_knowledgebase` and
`triage_case` rejected.

Also corrects the "nothing defines it" claim in three places — the
`customer_360` docstring, its changeset, and `code_examples.md`. The
skill still does not reference the tool, for a narrower and accurate
reason: retrieval needs a declared knowledge source, `AIKnowledgeSchema`
mounts only on `AgentSchema.knowledge`, and #512 deleted the agents — so
a skills-only app has nowhere to declare one and the tool would resolve
and return nothing. The skill's instruction line now says the model has
no such tool *in this skill*, rather than that none exists.

168 tests pass, typecheck and build clean, validate holds at its 2
pre-existing warnings.

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

…in CI (objectstack-ai#493)

`customer_360` declared `tools: ['search_knowledge']` — the survivor of the
eleven fictional tools objectstack-ai#493 counted, missed by objectstack-ai#512 because that skill
looked "already correct". The runtime silently drops an unresolved tool,
so the skill shipped with its only declared capability resolving to
nothing, while its instructions promised an account + cases +
opportunities + knowledge roll-up it had no tool to read.

Defining the missing tool was never the fix: `ToolSchema` is a read-only
Studio projection — no `implementation` field, no executor loads it — so a
hand-authored `search_knowledge` would validate, build, and still never
run. And the knowledge base here is not a search service: it is
`crm_knowledge_article`, a normal object. The skill now reads it with
`query_records` alongside the contacts, cases and opportunities the
description already promised, and quotes totals from `aggregate_data`.

Adds `test/skills-integrity.test.ts` (its own file — metadata-references
is a busy merge surface):

- every skill tool resolves to a platform built-in or an `action_<name>`
  tool materialised from a real Action, with wildcard subscriptions
  resolved by prefix;
- every referenced Action is `ai.exposed` with a ≥40-char LLM description
  AND a headless path (flow with a defined target, or a script body) —
  the regression objectstack-ai#512's follow-up commit had to fix by hand;
- stack tool metadata cannot be used to satisfy a dangling reference,
  since it never executes;
- every skill handed off to in instructions exists — the defect that
  pointed `case_triage` at a `response_drafting` skill that was never
  defined.

Each guard verified against the real defect before landing: reinstating
`search_knowledge`, `action_escalate_case` and the `response_drafting`
hand-off each fails its own assertion.

Also corrects two stale docstrings. `case_triage` and `email_drafting`
justified their read-only posture by calling `escalate_case`,
`close_case` and `send_email` `type: 'modal'` with no headless path;
objectstack-ai#515 and the send_email rewrite retyped all three to flow/script. The
posture is right, the reason was wrong — none of the three opts in via
`ai.exposed` (ADR-0011 is default off), so no tool is materialised and
the human review step stays a deliberate governance call.

typecheck, validate, build and the full suite pass (146 tests, +6).

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