---
id: 08-rewrite-agent-docs
epic: platform-retrofit
title: Rewrite CLAUDE.md and AGENTS.md for Veect
type: technical-story
status: todo
feature: docs
depends-on:
  [
    01-commit-product-docs,
    02-single-version-release-please,
    03-delete-demo-apps-and-features,
    04-web-next-shell,
    05-scaffold-optional-cores,
  ]
blocks: []
created: 2026-07-12T10:22:00Z
---

## Goal

CLAUDE.md and AGENTS.md describe Veect: control-plane/runner vocabulary, the new package map (auth + core packages, `apps/{web-next,cms,storybook}`, no demo features, no web-tanstack), ADR-027/028/029 references, the single-root versioning policy, and `docs/product/` as the authoritative spec location. The "15 conformance rules" miscount is fixed to sixteen.

## Why

Agent context is assembled from these files; today they describe a blog/CMS starter, so generated epics use the wrong vocabulary and package map (PRD user story 3). This story lands last because the docs describe the state the other stories produce.

## Done when

- CLAUDE.md and AGENTS.md project-overview sections describe Veect (spot check: no mention of blog/media/marketing-pages/navigation or web-tanstack as live packages/apps).
- Control-plane/runner vocabulary and ADR-027/028/029 references are present; `docs/product/` appears where the spec is referenced.
- CLAUDE.md's versioning bullet reflects the root-only release-please policy (story 02), and the "15 conformance/\* rules" Quick Start miscount reads sixteen, matching the enumerated rule list.
- Stale artifacts of the deletions are gone from both files (ports table, Sentry DSN trio, five-feature package lists).
- `docs/glossary.md` needs no further changes here — the Veect domain section already exists and deleted-feature terms were pruned in story 03's slices; verify only.
- `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff` pass on each commit.

## In scope

- CLAUDE.md: project overview, Read First, key conventions/versioning bullets, ports/DSN references, conformance-rule count.
- AGENTS.md: package map, boundary rules, per-package conventions sections.

## Out of scope

- Glossary edits (handled in story 03's deletion slices; Veect section already exists).
- Guide rewrites under `docs/guides/` beyond what CLAUDE.md/AGENTS.md link corrections force.
- Generator template documentation changes (generators stay as-is per PRD).

## Tasks

- [ ] Rewrite CLAUDE.md for Veect — project overview and Read First (control-plane/runner vocabulary, new package map, ADR-027/028/029 + `docs/product/` references), versioning bullet updated to the root-only policy, ports/DSN/feature lists purged of deleted packages, and the "15 conformance rules" miscount fixed to sixteen — one commit, all gates pass.
- [ ] Rewrite AGENTS.md for Veect — package map, boundary rules, and per-package conventions reflecting auth + cores + the three surviving apps, same vocabulary and ADR references as CLAUDE.md — one commit, all gates pass.
