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

[yinlianghui]

Description

Follow-up to #557, which closed #493. That issue's scoping comment noted the agent half was already retired; this cleans up the docs that never got the memo.

#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. docs/developers/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, per the note 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: validation sees a well-formed string and stops, so the reference rots silently and the next reader — human or agent — gets sent somewhere that does not exist.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring
• Performance improvement
• CI/CD update

Related Issues

Related to #493, #511, #512, #557

Changes Made

• 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.md 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 from the worked example (SkillSchema has no such field and strips it silently, fix(skills): drop the per-skill permissions keys — the field does not exist in SkillSchema #511), and fill the gap the deletions leave. The example now states 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.
• docs/ARCHITECTURE.md — same note, plus the case_triage skill its table had been missing.
• test/docs-drift.test.ts — new repo-tree guard: every src/<dir>/ a maintainer doc names must resolve on disk. docs/archive/ is deliberately excluded; it is a historical record and is allowed to describe a repo that no longer exists.

Testing

• Unit tests pass (npx vitest run) — 12 files, 155 tests (+9)
• Linting passes (npx objectstack lint --skip-i18n)
• Build succeeds; objectstack validate passes with the 2 pre-existing campaign_enrollment flow-variable warnings
• Manual testing completed — the guard earned its place immediately by failing on a stray "no src/agents/" parenthetical in this change's own first pass. Reworded rather than adding a negation-aware exception: a simple guard that occasionally forces clearer prose beats a clever one.
• New tests added (if applicable)

Checklist

• I have added a changeset (.changeset/docs-retired-agent-cube-directories.md, patch)
• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Additional Notes

Scope note: CHANGELOG.md and docs/archive/ still mention the agents. Both are historical records and are correct as written — the changelog entry even points at #512 for the retirement. Left untouched, and docs/archive/ is excluded from the guard for that reason.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y9STuduWbrAwcgviziaV4e

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Jul 31, 2026 2:43am