@taskset/cli 5.1.0 → 6.1.0

package/docs/configuration.md

@@ -1,13 +1,32 @@
 ---
-title: Configuration
-description: How taskset.config.ts identifies and configures a Taskset repository.
+title: Configure Taskset defaults
+description: Optionally add taskset.config.ts to overlay defaults and vocabulary on a `.taskset/` repository.
+contentType: How-to
+navLabel: Configuration
 ---
 
-# Configuration
+# Configure Taskset defaults
 
-Taskset usage begins with `taskset.config.ts` at the repository root. Commands
-started in nested packages or directories walk upward until they find this
-file.
+Taskset repositories are identified by a `.taskset/` directory. `taskset.config.ts` is optional. When the file is absent, built-in statuses, priorities, and creation defaults apply.
+
+## When to add a config file
+
+Add `taskset.config.ts` when you need at least one of these:
+
+- A repository `project.name`
+- Different task creation defaults
+- A reduced or reordered status or priority vocabulary
+- Closeout gates for parent/child completion, open concerns, or required lessons
+- Taxonomy allowlists for labels, projects, or concern classes
+- Extra doctor checks for ownerless concerns or stale research
+
+Create one during init:
+
+```bash
+taskset init --config
+```
+
+Or author the file beside `.taskset/`:
 
 ```typescript
 import { defineConfig } from '@taskset/cli'
@@ -25,37 +44,40 @@ export default defineConfig({
 		statuses: ['todo', 'doing', 'blocked', 'done', 'canceled'],
 		priorities: ['low', 'medium', 'high', 'urgent'],
 	},
+	closeout: {
+		enforceChildCompletion: false,
+		blockDoneWithOpenConcerns: false,
+		requireLessonWhenLabeled: [],
+	},
+	taxonomy: {
+		// omit allowlists for permissive behavior
+		mode: 'error',
+	},
+	doctor: {
+		activeConcernRequiresOwner: false,
+		// staleResearchDays: 14,
+	},
 })
 ```
 
 ## Contract
 
-- `project.name` is optional repository metadata.
-- `tasks.defaults.status`, `priority`, and `labels` are optional defaults used
-  by task creation.
-- `tasks.statuses` selects and orders the repository's active status vocabulary
-  from Taskset's canonical values. Task creation, updates, lifecycle changes,
-  listing, generated views, and diagnostics reject or report task statuses
-  outside that list. The default status must be included.
-- `tasks.priorities` selects and orders the repository's active priority
-  vocabulary from Taskset's canonical values. Task creation rejects a priority
-  outside that list, and the default priority must be included.
-- `urgent` is the highest supported priority. Taskset does not maintain a
-  separate urgency field because two overlapping importance scales make task
-  ordering harder to understand and keep consistent.
-- Unknown fields, invalid enum values, empty names, and duplicate default
-  labels or vocabulary values are rejected.
-- The config file is executable trusted project code and may use erasable
-  TypeScript syntax supported by the repository's Node version.
-
-The config identifies behavior; it is not task storage. Canonical task state
-remains under `.taskset/tasks/`, regardless of configuration.
+- `project.name` is optional repository metadata
+- `tasks.defaults.status`, `priority`, and `labels` are optional creation defaults
+- `tasks.statuses` selects and orders the active status vocabulary from Taskset’s canonical values
+- `tasks.priorities` selects and orders the active priority vocabulary from Taskset’s canonical values
+- `urgent` is the highest supported priority
+- `closeout.*` defaults to off / empty so existing repositories keep current done transitions
+- `taxonomy.labels`, `projects`, and `concernClasses` are optional allowlists; omit them to stay permissive
+- `taxonomy.mode` is `error` or `warn` when an allowlist is configured
+- `doctor.activeConcernRequiresOwner` and `doctor.staleResearchDays` add optional diagnostics
+- Unknown fields, invalid enum values, empty names, and duplicate default labels or vocabulary values are rejected
+- The config file is trusted project TypeScript and may use erasable syntax supported by your Node version
+
+The config identifies behavior. It is not task storage. Canonical task and document state remains under `.taskset/`.
 
 ## Discovery
 
-`taskset init` creates a minimal config when one does not exist and initializes
-`.taskset/tasks/`. Other commands require a discoverable config and report an
-error when run outside a Taskset repository.
+Commands started in nested directories walk upward until they find `.taskset/`. If `taskset.config.ts` exists at that root, Taskset loads and validates it. Otherwise it uses built-in defaults.
 
-Use `taskset config --json` to inspect the discovered root and resolved
-defaults.
+Use `taskset config --json` to inspect the discovered root, whether a config file is present, and the resolved defaults.

package/docs/document-types.md

@@ -1,14 +1,13 @@
 ---
-title: Document Types
-description: Canonical stories, flows, decisions, research, and runbooks.
+title: Choose a Taskset document type
+description: Canonical stories, flows, decisions, research, runbooks, lessons, concerns, and audits.
+contentType: Conceptual
+navLabel: Document Types
 ---
 
-# Document Types
+# Choose a Taskset document type
 
-Taskset stores durable project context beside tasks without forcing every note
-into a task lifecycle. Each type has strict common frontmatter and a body
-template suited to its purpose. Documents use the same planning, people, path,
-and relationship metadata fields as tasks, with document-specific statuses.
+Documents are how Taskset keeps product, engineering, and operational memory: what to build, what you learned, what you decided, how to recover, which mistakes not to repeat, and which residual risks remain open. Use them when the material should outlive a single task. Each type has strict common frontmatter and a body template suited to its purpose. Documents share planning, people, path, and relationship fields with tasks, and use document-specific statuses.
 
 | Type | Directory | Template focus |
 | --- | --- | --- |
@@ -17,6 +16,9 @@ and relationship metadata fields as tasks, with document-specific statuses.
 | `decision` (`adr`, `dr`) | `.taskset/decisions/` | context, decision, alternatives, consequences |
 | `research` | `.taskset/research/` | question, sources, findings, recommendation |
 | `runbook` | `.taskset/runbooks/` | symptoms, checks, actions, rollback, escalation |
+| `lesson` (`antipattern`) | `.taskset/lessons/` | trigger, incorrect/correct pattern, severity, prevention |
+| `concern` | `.taskset/concerns/` | summary, class, trust boundary, residual risk, cadence |
+| `audit` | `.taskset/audits/` | scope, method, findings, residual items, follow-ups |
 
 Create a document from its template:
 
@@ -24,13 +26,33 @@ Create a document from its template:
 taskset document create story --title "Member signs in via SSO"
 taskset document create flow --title "Recover a delayed deposit"
 taskset document create adr --title "Use transactional outbox"
-taskset document create research --title "Evaluate queue providers" --related <task-id>
+taskset document create research --title "Evaluate cloud providers" --related your_task_id_here
 taskset document create runbook --title "Recover consumer lag"
+taskset document create lesson --title "Capability flags are enablement only" --severity high --related your_task_id_here
+taskset document create concern --title "Telegram capability must not grant CASL" --class authz --cadence on-release
+taskset document create audit --title "Public route inventory"
 ```
 
-IDs and filenames use a per-type seven-digit sequence and title slug, for
-example `.taskset/flows/0000001-member-signs-in-via-sso.md`. Disposable metadata
-indexes for that kind live beside the files in `.taskset/flows/.generated/`.
+Document IDs are immutable 5-6 character lowercase hex values. Filenames keep a
+per-type display sequence and title slug, for example
+`.taskset/flows/0000001-member-signs-in-via-sso-a1b2c3.md`. Agents and commands
+use the short `id` in CLI flags and frontmatter relationships. The sequence
+prefix is display metadata only. Markdown hyperlinks to the file must use the
+repository-relative filepath. Disposable metadata indexes for that kind live
+beside the files in `.taskset/flows/.generated/`.
+
+Default statuses: `decision` → `accepted`; `runbook`, `lesson`, and `concern` →
+`active`; other kinds → `draft`.
+
+## Kind-specific metadata
+
+| Kind | Options |
+| --- | --- |
+| `lesson` | `--severity low\|medium\|high\|critical`, repeatable `--related-skill`, repeatable `--pack` |
+| `concern` | `--class security\|privacy\|money\|authz\|concurrency\|ops\|compliance\|other`, `--cadence <value>` |
+
+Clear lesson/concern scalars and arrays on update with `--clear-severity`,
+`--clear-related-skills`, `--clear-packs`, `--clear-class`, and `--clear-cadence`.
 
 ## Query And Mutation
 
@@ -38,6 +60,8 @@ Documents support the same command surface as tasks:
 
 ```bash
 taskset document list research --search "queue" --owner platform --impact
+taskset document list concern --directory apps/foo --status active --class authz --json
+taskset document list lesson --search "casl" --severity high --json
 taskset document show <document-id> --type research --include-derived --json
 taskset document update <document-id> --status ready --label infra --file packages/core
 taskset document status <document-id> accepted --type decision
@@ -51,21 +75,23 @@ Statuses are `draft`, `ready`, `active`, `accepted`, `superseded`, and
 ## Import Existing Markdown
 
 Use `document import` when a repository already has material under paths such
-as `docs/stories`, `docs/flows`, `docs/adr`, `docs/research`, or
-`docs/runbooks`:
+as `docs/stories`, `docs/flows`, `docs/adr`, `docs/research`, `docs/runbooks`,
+`docs/lessons`, `docs/concerns`, or `docs/audits`:
 
 ```bash
 taskset document import docs/flows/0001-sign-in.md
 taskset document import docs/architecture/use-postgres.md --type decision
+taskset document import docs/lessons/capability.md --move
 taskset document import docs/runbooks/consumer-lag.md --move
 ```
 
 The type is inferred from recognized parent directory names when `--type` is
 omitted. `adr`, `dr`, `decision`, and `decisions` all normalize to `decision`.
-The first H1 supplies the title unless `--title` is passed. Existing
-frontmatter is replaced with Taskset's canonical metadata while the Markdown
-body is preserved. Import copies by default; `--move` removes the source only
-after the canonical file has been written successfully.
+`antipattern` / `lessons` normalize to `lesson`. The first H1 supplies the title
+unless `--title` is passed. Existing frontmatter is replaced with Taskset's
+canonical metadata while the Markdown body is preserved. Import copies by
+default; `--move` removes the source only after the canonical file has been
+written successfully.
 
 Use `document list [type]`, `document show <id>`, and `--json` for inspection
 and automation. Sequences are per type, so pass `--type` to `document show`
@@ -82,8 +108,8 @@ safe for automation.
 [
   { "action": "create", "input": { "type": "story", "title": "Member upgrades" } },
   { "action": "import", "sourcePath": "docs/flows/checkout.md", "options": { "type": "flow" } },
-  { "action": "update", "id": "0000001-member-upgrades", "type": "story", "input": { "status": "ready" } },
-  { "action": "export", "id": "0000001-member-upgrades", "type": "story", "targetPath": "exports/member-upgrades.md" }
+  { "action": "update", "id": "a1b2c3", "type": "story", "input": { "status": "ready" } },
+  { "action": "export", "id": "a1b2c3", "type": "story", "targetPath": "exports/member-upgrades.md" }
 ]
 ```
 
@@ -93,8 +119,11 @@ taskset sync --concurrency 8
 ```
 
 `taskset sync` creates missing document-kind directories inside `.taskset`,
-migrates legacy task filenames and references throughout repository text files,
-refreshes data `.gitignore` rules for scoped `.generated/` directories, removes
-legacy global `.taskset/generated/`, and rebuilds generated views. Build
-outputs, dependencies, caches, snapshots, and Git internals are excluded from
-reference rewriting.
+migrates legacy task and document IDs to short hex IDs, normalizes
+`{sequence}-{slug}-{id}.md` filenames, repairs duplicate sequence prefixes by
+`createdAt`, rewrites repository text references, refreshes data `.gitignore`
+rules for scoped `.generated/` directories, removes legacy global
+generated directories, and rebuilds disposable views.
+
+For the chooser between task bodies and document kinds, see
+[Memory model](memory-model.md).

package/docs/getting-started.md

@@ -1,99 +1,111 @@
 ---
-title: Getting Started
-description: Initialize Taskset in a project and create the first repository task.
+title: Start a Taskset repository
+description: Install the CLI, initialize `.taskset/`, and capture your first plan, decision, and task in any language repository.
+contentType: Tutorial
+navLabel: Getting Started
 ---
 
-# Getting Started
+# Start a Taskset repository
 
-Taskset keeps project work in human-readable Markdown beside the code. The
-current pre-alpha release is intended for local repository use.
+This guide initializes Taskset in a repository and walks one delivery loop: capture intent, record research or a decision, then track the work. You do not need a JavaScript app, and you do not need `taskset.config.ts`.
 
 ## Requirements
 
-- Node.js 24 or newer
-- pnpm 11 or newer
+- Node.js 24 or newer to run the published CLI
+- Any Git repository or project root you can write to
 
-## Install
+## Install the CLI
 
-Install the published package as a development dependency in the project that
-will own the tasks:
+Pick one install style:
+
+```bash
+npx @taskset/cli@latest --help
+```
 
 ```bash
 pnpm add --save-dev @taskset/cli
 ```
 
-The package exposes the `taskset` executable.
+```bash
+npm install --global @taskset/cli
+```
+
+The package exposes the `taskset` executable. Package runners work in repositories that never declare a Node dependency.
 
-## Initialize
+## Initialize the repository
 
-Run Taskset from the repository root:
+Run init from the repository root, or from a nested directory when Git or workspace markers identify the root:
 
 ```bash
-pnpm taskset init
+taskset init
 ```
 
 This creates:
 
 ```text
-taskset.config.ts
 .taskset/
 ├── .gitignore
-└── tasks/
+├── tasks/
+├── stories/
+├── flows/
+├── decisions/
+├── research/
+└── runbooks/
 ```
 
-The config controls validated defaults. Task Markdown under `.taskset/tasks/`
-remains the canonical project state. The nested ignore file excludes
-`.taskset/cache/`, per-entity `.generated/` directories, and `.taskset/snapshots/`.
-Snapshots are non-authoritative safety checkpoints; tasks remain canonical.
-
-## Create And Inspect Work
+Add an optional config file only when you need custom task defaults:
 
 ```bash
-pnpm taskset task create --title "Add repository validation"
-pnpm taskset task list
-pnpm taskset task show <task-id>
-pnpm taskset task update <task-id> --status doing
+taskset init --config
 ```
 
-Task files can also be read and reviewed directly without Taskset installed.
+The nested ignore file excludes `.taskset/cache/`, per-entity `.generated/` directories, and `.taskset/snapshots/`. Snapshots are non-authoritative safety checkpoints. Markdown under `.taskset/` remains canonical.
+
+## Capture intent, then track delivery
 
-## Query And Validate Work
+Start with the durable context, then create the task that implements it:
 
 ```bash
-pnpm taskset task list --status doing --label core --json
-pnpm taskset task list --file packages/core --impact --json
-pnpm taskset doctor
+taskset document create story --title "Member signs in via SSO"
+taskset document create research --title "Compare SSO providers" --related your_story_id_here
+taskset document create adr --title "Use OIDC for member SSO" --related your_research_id_here
+taskset task create --title "Add SSO callback handler" --related your_decision_id_here --file packages/api/src/auth.ts
+taskset task list
+taskset document list --json
 ```
 
-File and directory filters use normalized repository-relative containment
-matching. With `--impact`, list output groups direct matches and tasks that
-transitively depend on them. Other filters select the direct set before graph
-expansion. `doctor` reports all readable format and graph failures in one
-non-mutating pass.
+You can read every file directly in the editor without the CLI. Use short hex
+`id` values in commands and `--related`. Filename sequence prefixes are display
+metadata only. Markdown hyperlinks to entity or docs files must use the
+repository-relative filepath (for example [document types](document-types.md)).
 
-## Generated Views And Migration
+## Query and validate the graph
 
 ```bash
-pnpm taskset generate
-pnpm taskset snapshot create
-pnpm taskset snapshot list
+taskset task list --status doing --label core --json
+taskset document list research --search "SSO" --json
+taskset task list --file packages/api --impact --json
+taskset doctor
 ```
 
-Snapshot restore previews by default unless `--apply` is present.
+File and directory filters use repository-relative containment. With `--impact`, list output groups direct matches and work that transitively depends on them. `doctor` reports readable format and graph failures in one non-mutating pass.
 
-## Complete Or Remove Work
+## Finish or remove work
 
 ```bash
-pnpm taskset task status <task-id> done
-pnpm taskset task delete <task-id>
+taskset task status your_task_id_here done
+taskset document status your_research_id_here accepted --type research
+taskset task delete your_task_id_here
 ```
 
-Completed and canceled tasks are terminal. Deletion fails while another task
-depends on the target. Use `--remove-dependencies` only when Taskset should
-remove those inbound references and the task together.
+Completed and canceled tasks are terminal. Deletion fails while another task depends on the target. Use `--remove-dependencies` only when Taskset should remove those inbound references and the task together.
 
 ## Next
 
-- [Configure task defaults](configuration.md)
-- [Use the complete CLI reference](cli-reference.md)
+- [Choose a document type](document-types.md)
+- [Choose memory layers](memory-model.md)
 - [Understand task files](task-files.md)
+- [Configure defaults](configuration.md)
+- [Use the complete CLI reference](cli-reference.md)
+- [Follow the agent guide](agents/index.md)
+- [Query recipes for agents](agents/query-recipes.md)

package/docs/index.md

@@ -1,37 +1,49 @@
 ---
-title: Taskset
-description: Offline, inline, AI-friendly project awareness stored beside the code.
+title: Keep the whole delivery story beside the code
+description: Taskset stores plans, research, decisions, runbooks, lessons, concerns, audits, and tasks as Markdown in your repository for agents and humans.
+contentType: Landing
+navLabel: Overview
 ---
 
-# Taskset
+# Keep the whole delivery story beside the code
 
-Taskset is an offline, inline, AI-friendly, human-readable task manager designed
-to accelerate software delivery and give development teams immediate awareness
-of the work surrounding their code.
+Taskset is a local-first delivery workspace. You keep stories, research, decisions, flows, runbooks, lessons, concerns, audits, and executable tasks as Markdown under `.taskset/`, so agents and humans share one reviewable source of truth.
 
-Tasks and project knowledge live inside the repository as Markdown. Git supplies
-history, branches, review, and collaboration. Taskset supplies a consistent
-domain model and interfaces over those files.
+Install the CLI as `@taskset/cli` from npm. Run it with `npx`, `pnpm dlx`, `yarn dlx`, `bunx`, a project dependency, or a global install.
 
-Install the command-line package from npm as `@taskset/cli`.
+## What belongs in Taskset
 
-## Core Promise
+- **Plan**: stories and flows that define outcomes and journeys
+- **Learn**: research that captures evidence and recommendations
+- **Decide**: decisions and ADRs that lock lasting choices
+- **Operate**: runbooks that make recovery safe to repeat
+- **Remember**: lessons, concerns, and audits for recurring patterns and residual risk
+- **Deliver**: tasks that carry ownership, status, dependencies, and code impact
 
-- Work remains readable without Taskset installed.
-- Developers can operate locally without a mandatory service.
-- Humans and AI agents inspect the same project context.
-- CLI, TUI, MCP, editor, Kanban, and reporting views share one source of truth.
-- Monorepo projects and code relationships are first-class.
+Documents preserve memory. Tasks move work. Relationships keep the graph honest.
 
-## Current Status
+## What you get
 
-Taskset is pre-alpha. The CLI supports repository initialization, configuration
-inspection, validated task CRUD and lifecycle changes, repository diagnostics,
-generated views, snapshots, metadata queries, and file-impact analysis.
+- Project knowledge stays in the repository it describes
+- Markdown remains readable without Taskset installed
+- Agents and humans inspect the same plans, decisions, and work
+- CLI, skills, and future interfaces share one domain model
+- Monorepo paths and code relationships are first-class
 
-## Read Next
+## What the CLI covers
 
-- [Getting started](getting-started.md)
-- [Configuration](configuration.md)
-- [CLI reference](cli-reference.md)
-- [Task files](task-files.md)
+The CLI initializes repositories, manages optional configuration, creates and queries tasks and documents, runs diagnostics, builds generated views, snapshots state, and syncs the tree after upgrades or repairs.
+
+## Choose your path
+
+- [Start a Taskset repository](getting-started.md)
+- [Choose a document type](document-types.md)
+- [Choose memory layers](memory-model.md)
+- [Track security and compliance](security-compliance-tracking.md)
+- [Follow the agent closeout contract](agent-closeout.md)
+- [Control taxonomy](taxonomy-cookbook.md)
+- [Understand task files](task-files.md)
+- [Configure defaults when you need them](configuration.md)
+- [Look up every CLI command](cli-reference.md)
+- [Read agent workflows and contracts](agents/index.md)
+- [Copy-paste agent query recipes](agents/query-recipes.md)

package/docs/maintainers/architecture/decisions/0001-documentation-platform.md

@@ -1,70 +1,44 @@
 ---
 title: "ADR 0001: Documentation Platform"
-description: Render canonical user documentation through the Taskset website.
+description: Render canonical documentation through the Taskset website for humans, agents, and maintainers.
 ---
 
 # ADR 0001: Documentation Platform
 
 - Status: Accepted
 - Date: 2026-06-12
+- Updated: 2026-10-03
 
 ## Context
 
-Taskset needs one documentation source that is readable on Git hosts and can
-also power a documentation website. User guidance and repository maintenance
-material have different audiences and should remain visibly separated.
+Taskset needs one documentation source that is readable on Git hosts and can also power a documentation website. Human usage guidance, agent operating contracts, and repository maintenance material have different audiences and should remain visibly separated.
 
 ## Decision
 
-- Keep canonical user documentation in the root `docs/` directory.
-- Keep contributor, product, architecture, ADR, testing, and technology
-  material under `docs/maintainers/`.
-- Use plain Markdown by default and MDX only for interactive pages.
-- Build `apps/www` with Next.js App Router, Nextra, and the stock Nextra docs
-  and blog themes.
-- Expose root `docs/` as the app's Nextra `content` directory through a
-  repository-relative symlink.
-- Render top-level usage docs and `docs/maintainers/` through separate route
-  layouts and page maps so their navigation stays audience-specific.
-- Keep chronological release and project posts under `apps/www/posts/`.
-- Isolate usage docs, maintainer docs, and blog layouts and MDX component sets
-  by route.
-- Keep the Nextra configuration and layout close to the upstream defaults.
-
-Nextra supports App Router content-directory routing and typed `_meta.ts`
-navigation:
-
-- <https://nextra.site/docs/file-conventions/content-directory>
-- <https://nextra.site/docs/docs-theme/start>
+- Keep canonical documentation in the root `docs/` directory
+- Keep human usage pages at the top level of `docs/`
+- Keep agent operating guidance under `docs/agents/`, with root `AGENTS.md` and packaged `skills/` as offline entrypoints
+- Keep contributor, product, architecture, ADR, testing, and technology material under `docs/maintainers/`
+- Publish an agent discovery index at `apps/www/public/llms.txt` (served as `/llms.txt`); copy it into the packaged CLI docs for offline use
+- Use plain Markdown by default and MDX only for interactive pages
+- Build `apps/www` with Next.js App Router, Nextra, and the stock Nextra docs and blog themes
+- Expose root `docs/` as the app’s Nextra `content` directory through a repository-relative symlink
+- Render top-level usage docs (including `docs/agents/`) and `docs/maintainers/` through separate route layouts and page maps
+- Keep chronological release and project posts under `apps/www/posts/`
+- Follow the [Vercel writing guidelines](https://github.com/vercel-labs/writing-guidelines) for public prose voice and structure
 
 ## Why
 
-This matches the existing Next.js direction, provides navigation and search
-without a custom content loader, and keeps user documentation readable in its
-canonical location. Moving maintainer material into a dedicated
-`docs/maintainers/` section prevents the root README and user pages from
-becoming contributor handbooks.
+This keeps one Markdown source of truth while matching how agent-first tools expose denser contracts beside human onboarding. Maintainer material stays out of the primary product navigation. Agent pages and `llms.txt` give coding agents a short index without inventing a second product truth.
 
 ## Implementation Contract
 
-`apps/www/content` points to `../../docs`. The usage docs catch-all route loads
-top-level content and excludes `docs/maintainers/` from its page map. The
-`/maintainers` route loads the same content directory with a maintainer-rooted
-page map. The app may generate `.next/`, search data, and static output, but
-none of those become documentation source.
-
-`apps/www/posts/` is the source for blog Markdown. An app-local registry maps
-each post to `/posts/[slug]` so static export can enumerate routes without
-copying posts into `docs/`. The global MDX component file contains only base
-Nextra components; docs and blog routes apply their own theme components.
+`apps/www/content` points to `../../docs`. The usage docs catch-all route loads top-level content, including `docs/agents/`, and excludes `docs/maintainers/` from its page map. The `/maintainers` route loads the same content directory with a maintainer-rooted page map. Root `AGENTS.md` is repository-local agent guidance and may be linked from docs, but docs remain canonical for published pages. Do not place non-Markdown discovery files such as `llms.txt` under `docs/`; Nextra imports the content tree as modules and only Markdown/MDX pages belong there.
 
 ## Consequences
 
-- Documentation changes are reviewable without building the site.
-- Blog posts are reviewable as app-local Markdown without a CMS.
-- The site build must include root `docs/` files in its input.
-- New posts must be added to the app-local static post registry.
-- MDX components remain owned by `apps/www`.
-- Maintainer documentation is reviewed from `docs/maintainers/` and remains in
-  its own `/maintainers` navigation section.
-- Broken links and invalid frontmatter should fail CI.
+- Documentation changes are reviewable without building the site
+- Blog posts are reviewable as app-local Markdown without a CMS
+- New agent pages belong under `docs/agents/` and appear in usage navigation
+- Maintainer documentation remains in its own `/maintainers` navigation section
+- Broken links and invalid frontmatter should fail CI

package/docs/maintainers/development/contributing.md

@@ -5,8 +5,7 @@ description: Repository setup, Taskset dogfooding, pull requests, and completion
 
 # Contributing
 
-Taskset is pre-alpha. Strengthen the core file format and workflow before
-expanding the number of interfaces.
+Keep the core file format and workflow coherent when you change interfaces, packages, or docs.
 
 ## Start Here
 
@@ -27,7 +26,7 @@ Use the Node and pnpm versions declared by `.nvmrc` and `packageManager`.
 
 ## Develop Taskset With Taskset
 
-The repository dogfoods Taskset. Use the root `taskset.config.ts`, the CLI, and
+The repository dogfoods Taskset. Use the root `.taskset/` data, optional `taskset.config.ts`, the CLI, and
 canonical `.taskset/tasks/` files to plan and inspect work. When the CLI
 supports the required operation, update the task through the CLI instead of
 editing generated or derived state.