@codemcp/ade 0.6.1 → 0.8.0

package/.vibe/docs/architecture.md

@@ -0,0 +1,201 @@
+# ADE — System Architecture (C4 Model)
+
+## 1. System Context (C4 Level 1)
+
+### System Overview
+
+ADE (Agentic Development Environment) is a CLI tool that lets engineering teams declare _what_ their project needs for agentic development — workflow conventions, skills, knowledge sources, tools — and generates the correct agent-specific configuration files for whichever coding agent they use. It bridges the gap between a team's abstract preferences and the per-agent config formats each AI coding assistant requires.
+
+### Users and Personas
+
+- **Individual developer**: Runs `ade setup` once to configure a project, then `ade install` on subsequent machines or CI environments to reproduce the setup.
+- **Tech lead / platform team**: Authors a shared `ade.extensions.mjs` that encodes org-specific conventions (custom skills, internal docsets, proprietary harnesses) and distributes it via a template repository.
+- **CI/CD pipeline**: Calls `ade install` to ensure a reproducible agent environment before agentic tasks run.
+
+### External Systems
+
+- **`@codemcp/skills`**: Manages SKILL.md files and the skills lock file. ADE calls its programmatic API (`runAdd`) to install skills into the project.
+- **`@codemcp/knowledge`**: Manages `.knowledge/config.yaml` and docset artifacts. ADE calls `createDocset` + `initDocset` to register and download knowledge sources.
+- **`@codemcp/workflows-server`** (and other MCP servers): Runtime servers registered as MCP server entries in the generated agent config. ADE writes the config; it does not start or manage these servers.
+- **Coding agents** (Claude Code, OpenCode, Copilot, Cursor, Kiro, etc.): Consumers of ADE's generated config files. Each has its own format; ADE's harness writers know the details.
+- **Skills server** (e.g. `mrsimpson/skills-coding`): External source for skill definitions referenced in catalog options.
+
+### System Boundaries
+
+- **Inside ADE**: Catalog, resolver, provision writers, harness writers, CLI TUI, lock file management, skills installer, knowledge installer.
+- **Outside ADE**: Runtime MCP servers, agent execution, skill content authoring, docset content management, the agents themselves.
+
+### Context Diagram
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                        Developer                        │
+└─────────────────────────┬───────────────────────────────┘
+                          │ ade setup / ade install
+┌─────────────────────────▼───────────────────────────────┐
+│                   ADE CLI (@codemcp/ade)                 │
+│  Interactive TUI + resolver + file generators           │
+└──────┬──────────────────┬──────────────────┬────────────┘
+       │ programmatic API │                  │ writes config files
+       ▼                  ▼                  ▼
+@codemcp/skills   @codemcp/knowledge   Agent config files
+(skills lock,     (.knowledge/         (AGENTS.md,
+ SKILL.md files)   config.yaml,         .mcp.json,
+                   docset artifacts)    opencode.json, …)
+```
+
+---
+
+## 2. Container Architecture (C4 Level 2)
+
+### Containers
+
+#### `@codemcp/ade-core` (`packages/core`)
+
+- **Technology**: TypeScript, pure functions, no I/O except config file reads/writes
+- **Responsibilities**: All types, catalog definitions, resolution logic, provision writers, writer registry
+- **Interfaces**: Public TypeScript API (`index.ts`) — exported types, `resolve()`, `createDefaultRegistry()`, `mergeExtensions()`, catalog accessors, config read/write utilities
+- **Data storage**: None at runtime; reads/writes `config.yaml` and `config.lock.yaml` via helper functions
+
+#### `@codemcp/ade-cli` (`packages/cli`)
+
+- **Technology**: TypeScript, `@clack/prompts` for TUI, `tsup` bundle
+- **Responsibilities**: Argument parsing, interactive TUI, extensions loading, skills installation, knowledge installation, command routing
+- **Interfaces**: CLI binary (`ade setup [dir]`, `ade install [dir]`); programmatic entry points `runSetup()` and `runInstall()` (used in tests)
+- **Data storage**: None; delegates to core for file I/O
+
+#### `@codemcp/ade-harnesses` (`packages/harnesses`)
+
+- **Technology**: TypeScript
+- **Responsibilities**: Per-agent config file writers (AGENTS.md, .mcp.json, opencode.json, .kiro/, etc.)
+- **Interfaces**: `allHarnessWriters`, `getHarnessWriter()`, `buildHarnessWriters()`, `installSkills()`, `writeInlineSkills()`
+- **Data storage**: Writes agent-specific config files to the project root
+
+### Container Interactions
+
+```
+ade setup/install
+  │
+  ├─► loadExtensions()        [cli → disk: ade.extensions.mjs]
+  ├─► mergeExtensions()       [cli → core]
+  ├─► resolve()               [cli → core: UserConfig + Catalog → LogicalConfig]
+  ├─► writeLockFile()         [cli → core → disk: config.lock.yaml]
+  ├─► harness.install()       [cli → harnesses → disk: agent config files]
+  ├─► installSkills()         [cli → harnesses → @codemcp/skills]
+  └─► installKnowledge()      [cli → @codemcp/knowledge API]
+```
+
+### Deployment
+
+ADE is a developer tool — it runs locally (`npx @codemcp/ade`) or in CI. There is no persistent service. The generated output files are checked into the project repository.
+
+---
+
+## 3. Component Architecture (C4 Level 3)
+
+### `@codemcp/ade-core` Components
+
+#### Catalog
+
+- **Responsibilities**: Declares all built-in facets and options as TypeScript objects; provides `getDefaultCatalog()`, `mergeExtensions()`, `sortFacets()`, `getVisibleOptions()`
+- **Key files**: `catalog/index.ts`, `catalog/facets/{process,architecture,practices,backpressure,autonomy}.ts`
+- **Design pattern**: Static data objects; no runtime state
+
+#### Resolver
+
+- **Responsibilities**: Expands `UserConfig` choices against the `Catalog` using the `WriterRegistry`; produces `LogicalConfig`; deduplicates MCP servers and skills by key; auto-adds `@codemcp/knowledge-server` when `knowledge_sources` are non-empty
+- **Key files**: `resolver.ts`
+- **Design pattern**: Pure function `resolve(userConfig, catalog, registry): Promise<LogicalConfig>`
+
+#### Writer Registry
+
+- **Responsibilities**: Maps writer IDs to `ProvisionWriterDef` instances; `createDefaultRegistry()` pre-registers all built-in writers; open for runtime extension
+- **Key files**: `registry.ts`
+- **Design pattern**: `Map`-based registry; open/closed principle — new writers added without modifying core
+
+#### Provision Writers (built-in)
+
+| Writer | File | Output |
+|---|---|---|
+| `workflows` | `writers/workflows.ts` | `mcp_servers[]` entry |
+| `skills` | `writers/skills.ts` | `skills[]` entries |
+| `docset` | `writers/docset.ts` | `knowledge_sources[]` entry |
+| `instruction` | `writers/instruction.ts` | `instructions[]` entry |
+| `git-hooks` | `writers/git-hooks.ts` | `git_hooks[]` entries |
+| `permission-policy` | `writers/permission-policy.ts` | `permission_policy` |
+| `setup-note` | `writers/setup-note.ts` | `setup_notes[]` entry |
+| `mcp-server` | `writers/mcp-server.ts` | `mcp_servers[]` entry |
+
+Each writer receives `Record<string, unknown>` config and narrows internally; the registry contract stays generic.
+
+#### Types
+
+- **Responsibilities**: Single source of truth for all shared interfaces — `Catalog`, `Facet`, `Option`, `Provision`, `LogicalConfig`, `KnowledgeSource`, `DocsetPreset`, `SkillDefinition`, `UserConfig`, `LockFile`, `WriterRegistry`, `AdeExtensions`, and their Zod validation schemas
+- **Key file**: `types.ts`
+
+### `@codemcp/ade-cli` Components
+
+#### Entry Point / Router (`index.ts`)
+
+Parses `process.argv`, loads extensions, builds catalog and harness writers, delegates to `runSetup` or `runInstall`.
+
+#### `runSetup` (`commands/setup.ts`)
+
+Walks the user through the TUI facet-by-facet, resolves choices, writes `config.yaml` + `config.lock.yaml`, runs harness writers, installs skills and offers knowledge initialization.
+
+#### `runInstall` (`commands/install.ts`)
+
+Reads `config.lock.yaml`, runs harness writers, installs skills, and calls `installKnowledge` — no re-resolution.
+
+#### Extensions Loader (`extensions.ts`)
+
+Finds and loads `ade.extensions.{ts,mjs,js}` from the project root. Uses `jiti` for TypeScript files. Validates with `AdeExtensionsSchema`.
+
+#### Knowledge Installer (`knowledge-installer.ts`)
+
+Wraps `createDocset` + `initDocset` from `@codemcp/knowledge`. Handles "already exists" gracefully (proceeds to `initDocset`). Passes `preset` from `KnowledgeSource` (default: `"git-repo"`).
+
+---
+
+## 4. Architecture Decisions
+
+### Docsets as `docset` provision writer (not `Option.docsets[]`)
+
+**Decision**: Documentation sources are declared as `{ writer: "docset", config: { id, label, origin, description, preset? } }` recipe entries, identical in structure to skills provisions.
+
+**Rationale**: The old `Option.docsets[]` sibling field was a parallel mechanism that bypassed the writer registry, required a separate opt-out multiselect prompt, and introduced `excluded_docsets` in `UserConfig`. The writer model is already the right abstraction — using it for docsets makes the catalog uniform, removes per-item opt-out UX, and lets extensions contribute docsets with the same syntax as everything else.
+
+**Consequences**: `DocsetDef`, `collectDocsets()`, and `excluded_docsets` removed. Setup prompt simplified to a single opt-in confirm.
+
+### Two-package split: `core` + `cli`
+
+**Decision**: All types, logic, and writers live in `@codemcp/ade-core`. The CLI is a thin shell.
+
+**Rationale**: Core can be imported programmatically (CI scripts, tests, extensions) without pulling in TUI dependencies. It also enables the harnesses package to depend on core without depending on the CLI.
+
+### `LogicalConfig` as the stable contract
+
+**Decision**: Provision writers produce `Partial<LogicalConfig>`; harness writers consume `LogicalConfig`. Neither knows about the other.
+
+**Rationale**: Decouples the catalog / resolution side from the file-generation side. Adding a new harness requires no changes to writers; adding a new writer requires no changes to harnesses.
+
+### Lock file is the install source of truth
+
+**Decision**: `ade install` reads `config.lock.yaml` directly; it never re-resolves from `config.yaml`.
+
+**Rationale**: Mirrors `npm ci` / `package-lock.json`. Makes installs deterministic and reviewable. `config.lock.yaml` is checked in, so CI produces exactly what was reviewed.
+
+### Open registry for extensibility
+
+**Decision**: `WriterRegistry` is a `Map`-based runtime registry, not a discriminated union.
+
+**Rationale**: A discriminated union is a closed set — adding a writer from an extension package would require modifying core. The registry is open: any package can register a writer before `resolve()` runs.
+
+---
+
+## 5. References
+
+- Existing CLI design doc: `docs/CLI-design.md`
+- Existing CLI PRD: `docs/CLI-PRD.md`
+- Extensions guide: `docs/guide/extensions.md`
+- Example extension: `ade.extensions.mjs`

package/.vibe/docs/design.md

@@ -0,0 +1,179 @@
+<!--
+DESIGN DOCUMENT TEMPLATE - TIERED BY PROJECT COMPLEXITY
+
+PURPOSE: Document design principles, patterns, and standards that guide implementation.
+NOTE: Technology stack decisions belong in the Architecture Document, not here.
+
+PROJECT COMPLEXITY GUIDE:
+🚀 ESSENTIAL (Startup/MVP, 1-3 developers, <6 months): Sections 1-2 only
+🏢 CORE (Small team, 2-5 developers, 6-18 months): Sections 1-4
+🏗️ ADVANCED (Enterprise, 5+ developers, 18+ months): Sections 1-5
+⚡ SPECIALIZED (Mission-critical, high reliability): All sections + custom
+
+WHAT TO INCLUDE:
+✅ Design principles and patterns
+✅ Naming conventions and standards
+✅ Component design approaches
+✅ Data modeling principles
+✅ Quality attribute design strategies
+❌ Technology stack choices (goes in Architecture doc)
+❌ Concrete class names or implementations
+❌ Code snippets or method signatures
+
+START SMALL: Begin with Essential sections, add more as project matures.
+
+IMPORTANT: DO NOT REMOVE THIS COMMENT HOW TO USE THE TEMPLATE!
+-->
+
+# ADE — Design Document
+
+## 1. Naming Conventions
+
+### Types and Interfaces
+
+- **PascalCase** for all TypeScript interfaces, type aliases, and enums: `LogicalConfig`, `KnowledgeSource`, `DocsetPreset`, `ProvisionWriterDef`.
+- Suffix `Def` for writer definition interfaces: `ProvisionWriterDef`, `AgentWriterDef`.
+- Suffix `Schema` for Zod validation schemas: `AdeExtensionsSchema`, `OptionSchema`.
+- Suffix `Writer` for instances of writers registered in the registry: `docsetWriter`, `skillsWriter`, `workflowsWriter`.
+- Suffix `Facet` for exported catalog facet objects: `architectureFacet`, `practicesFacet`.
+
+### Functions
+
+- **camelCase** throughout. Factory functions prefixed `create`: `createDefaultRegistry()`, `createRegistry()`. Reader/writer pairs prefixed `read`/`write`: `readLockFile()`, `writeLockFile()`. Accessor functions prefixed `get`: `getFacet()`, `getOption()`, `getProvisionWriter()`.
+- CLI entry points prefixed `run`: `runSetup()`, `runInstall()`.
+
+### Files
+
+- One primary export per file; file name matches the export name in kebab-case: `docset.ts` exports `docsetWriter`, `knowledge-installer.ts` exports `installKnowledge`.
+- Test files co-located: `docset.ts` → `docset.spec.ts`. Integration tests suffixed `.integration.spec.ts`.
+
+### Writer IDs
+
+- Kebab-case string IDs matching the file name: `"docset"`, `"git-hooks"`, `"permission-policy"`, `"setup-note"`.
+
+---
+
+## 2. Error Handling Design
+
+### Provision Writers
+
+Writers throw on invalid config. The resolver does not catch writer errors — a bad catalog entry or extension config fails loudly at setup time, not silently at runtime.
+
+### Knowledge Installer
+
+`createDocset` "already exists" errors are swallowed and execution falls through to `initDocset` (idempotency). All other `createDocset` errors and all `initDocset` errors are logged as warnings and skipped — one failing source does not block the rest.
+
+### Extensions Loading
+
+`AdeExtensionsSchema.safeParse()` on loaded extension data. On failure, a descriptive error is thrown before any resolution runs: _"Invalid ade.extensions file at …"_.
+
+### Unknown Writer IDs
+
+`resolve()` throws if a recipe provision references a writer ID not present in the registry. This is a catalog authoring error and should fail loudly.
+
+### TUI Cancellation
+
+`clack.isCancel()` is checked after every prompt. On cancel, `clack.cancel()` is called and the function returns early (no partial writes).
+
+---
+
+## 3. Architecture Patterns & Principles
+
+### Registry Pattern for Open Extensibility
+
+The `WriterRegistry` is a `Map`-based runtime dispatch table. New provision writers are registered with `registerProvisionWriter(registry, writerDef)` before `resolve()` runs. This keeps the system open for extension without modifying core — any package contributing via `ade.extensions.mjs` can register custom writers.
+
+### Pure Function Resolution
+
+`resolve()` is a pure async function: `(UserConfig, Catalog, WriterRegistry) → LogicalConfig`. It has no side effects and no I/O. This makes it trivially testable and usable in non-CLI contexts.
+
+### Stable Interface Seam: `LogicalConfig`
+
+All provision writers produce `Partial<LogicalConfig>`. All harness writers consume `LogicalConfig`. This seam is the only contract between the two sides — writers don't know about agents, agents don't know about writers.
+
+### Data-Driven Catalog
+
+The catalog is plain TypeScript data (no classes, no inheritance). Facets and options are literal objects conforming to the `Facet` and `Option` interfaces. This makes the catalog easily serializable, diffable, and extensible via `mergeExtensions()`.
+
+### Opt-In Confirmation for Side Effects
+
+Long-running or network-bound operations (skills installation, knowledge init) are never performed silently. The TUI asks the user with a `confirm` prompt (default: `false` for knowledge, `true` for skills). `ade install` performs these unconditionally since it is non-interactive and the lock file represents the user's prior decision.
+
+---
+
+## 4. Component Design Strategy
+
+### Component Boundary Principles
+
+- **`core`** has zero runtime I/O except config file reads/writes. No TUI, no network, no process spawning.
+- **`cli`** is the I/O layer: TUI prompts, extension file loading, subprocess/API calls to `@codemcp/skills` and `@codemcp/knowledge`.
+- **`harnesses`** knows all agent config formats but nothing about how selections were made.
+
+### Responsibility Assignment
+
+Each provision writer is responsible for exactly one `LogicalConfig` field group. It receives an untyped `config` record and narrows internally — the registry contract stays generic while the implementation is specific.
+
+### Interface Design
+
+Writers are `interface`-typed (open contracts), not `class`-based. This allows any object literal conforming to the interface to be registered — no inheritance required, no framework needed.
+
+### Dependency Direction
+
+```
+cli → core ← harnesses
+cli → harnesses
+```
+
+`core` has no upward dependencies. `harnesses` depends on `core` for types. `cli` depends on both.
+
+---
+
+## 5. Data Design Approach
+
+### Two-File Config Model
+
+- **`config.yaml`** (user-facing): stores `choices` and optional `custom` overrides. CLI-managed except the `custom` block. Checked into the repo as a team-shared declaration.
+- **`config.lock.yaml`** (generated): stores the fully resolved `LogicalConfig` snapshot. Never hand-edited. The install source of truth — `ade install` reads this, never re-resolves.
+
+### LogicalConfig as Intermediate Representation
+
+`LogicalConfig` is agent-agnostic. It is the normalised representation of what the project needs, before it is translated into any agent's format. Fields are append-only lists (MCP servers, skills, knowledge sources, instructions) deduplicated by a stable key.
+
+### Deduplication Keys
+
+- MCP servers: deduplicated by `ref`
+- Skills: deduplicated by `name`
+- Knowledge sources: deduplicated by `name`
+
+### `DocsetPreset` Typing
+
+`KnowledgeSource.preset` uses the same literal union as `@codemcp/knowledge`'s `DocsetPreset` (`"git-repo" | "local-folder" | "archive"`), keeping the types aligned without re-exporting the dependency's internal types directly.
+
+---
+
+## 9. Extension and Evolution Strategy
+
+### Extension Points
+
+1. **`facetContributions`** — append options to existing facets (most common)
+2. **`facets`** — add entirely new facets
+3. **`provisionWriters`** — register custom writers for custom `config` shapes
+4. **`harnessWriters`** — add support for new coding agents
+
+All four are declared in `ade.extensions.{mjs,ts}` in the project root. The CLI loads and validates this file before every `setup` or `install` run.
+
+### Versioning Strategy
+
+The `config.lock.yaml` carries a `version: 1` field. Breaking changes to the lock file format increment this version. `ade install` can detect a stale lock file and prompt the user to re-run `ade setup`.
+
+### Catalog Evolution
+
+Built-in catalog options can be updated in place. Extension options that `replaces` a built-in skill name override it at resolution time without modifying the upstream catalog.
+
+---
+
+# Implementation Notes
+
+- Tests import `runSetup` / `runInstall` directly; the CLI binary entry point is thin enough to not need its own tests.
+- Integration tests mock `@clack/prompts` (TUI) and `@codemcp/knowledge` (network I/O) via `vi.mock`. All `confirm` mock return values must be set explicitly per test — `vi.clearAllMocks()` resets them to `undefined` (falsy).
+- The `ProvisionWriter` union in `types.ts` is a type-level hint; the real runtime guard is the registry. Adding a new writer requires registering it in `createDefaultRegistry()` and the union.

package/.vibe/docs/requirements.md

@@ -0,0 +1,17 @@
+# Requirements Placeholder
+
+This is a placeholder document. The user has chosen not to maintain separate requirements documentation for this project.
+
+## INSTRUCTIONS FOR LLM
+
+**DO NOT EDIT THIS FILE**
+
+- Use the current development plan file to specify requirements for ongoing development
+- Reference requirements from the plan file context when needed
+- Focus requirements discussion in the plan file's "Goal" and relevant task sections
+- When requirements clarification is needed, document them in the plan file rather than here
+- This placeholder ensures the workflow variables work correctly while respecting the user's choice
+
+## User's Choice
+
+The user has explicitly chosen not to use dedicated requirements documentation for this project. Please respect this decision and work with the plan file for requirements-related information.

package/ade.extensions.mjs

@@ -40,24 +40,22 @@ export default {
             }
           },
           {
-            writer: "knowledge",
+            writer: "docset",
             config: {
-              sources: [
-                {
-                  name: "sap-abap-docs",
-                  origin: "https://your-serialized-version-of-abap-docs.git",
-                  description: "Official SAP ABAP Cloud development guide"
-                }
-              ]
+              id: "sap-btp-docs",
+              label: "SAP BTP",
+              origin: "https://your-serialized-version-of-btp-docs.git",
+              description: "SAP Business Technology Platform documentation"
             }
-          }
-        ],
-        docsets: [
+          },
           {
-            id: "sap-btp-docs",
-            label: "SAP BTP",
-            origin: "https://your-serialized-version-of-btp-docs.git",
-            description: "SAP Business Technology Platform documentation"
+            writer: "docset",
+            config: {
+              id: "sap-abap-docs",
+              label: "SAP ABAP Cloud",
+              origin: "https://your-serialized-version-of-abap-docs.git",
+              description: "Official SAP ABAP Cloud development guide"
+            }
           }
         ]
       }

package/config.lock.yaml

@@ -1,5 +1,5 @@
 version: 1
-generated_at: 2026-03-19T09:28:46.177Z
+generated_at: 2026-03-20T08:32:04.912Z
 choices:
   process: codemcp-workflows
   practices:
@@ -18,6 +18,11 @@ logical_config:
       args:
         - "@codemcp/workflows-server@latest"
       env: {}
+      allowedTools:
+        - whats_next
+        - conduct_review
+        - list_workflows
+        - get_tool_info
     - ref: agentskills
       command: npx
       args:

package/docs/CLI-PRD.md

@@ -40,8 +40,9 @@ from that facet).
 
 ### Option
 
-One possible answer to a facet. Each option carries a recipe and optionally
-a list of recommended docsets.
+One possible answer to a facet. Each option carries a recipe list of
+provisions. Documentation sources (docsets) are declared as `docset`
+provisions in the recipe alongside skills and other provisions.
 
 ### Recipe
 
@@ -57,15 +58,13 @@ runtime config and agent instructions.
 
 ### Docset
 
-Documentation sources recommended by an option. Docsets are a **weak entity
-on Option** — they are always implied by an upstream selection (e.g. picking
-"TanStack" implies TanStack Router/Query/Form/Table docs). The TUI presents
-all implied docsets as pre-selected defaults and allows the user to deselect
-(opt-out, not opt-in). The resolver collects docsets from all selected
-options, deduplicates by id, filters by `excluded_docsets`, and maps them to
-`knowledge_sources` in LogicalConfig. When any knowledge sources are present,
-the resolver automatically adds a `@codemcp/knowledge-server` MCP server
-entry.
+Documentation sources declared as a `docset` provision in an option's
+recipe. Docsets are always implied by an upstream selection (e.g. picking
+"TanStack" implies TanStack Router/Query/Form/Table docs declared as
+`docset` provisions in the `tanstack` option's recipe). The `docsetWriter`
+maps each provision to a `KnowledgeSource` in LogicalConfig. When any
+knowledge sources are present, the resolver automatically adds a
+`@codemcp/knowledge-server` MCP server entry.
 
 ### Provision
 
@@ -76,15 +75,17 @@ carries writer-specific config. Provision types:
 | ------------- | ------------------------------------------------------------ |
 | `workflows`   | MCP server entry for `@codemcp/workflows-server`             |
 | `skills`      | Skill definitions (inline or external) for `@codemcp/skills` |
-| `knowledge`   | Knowledge source entry for `@codemcp/knowledge`              |
+| `docset`      | Knowledge source entry for `@codemcp/knowledge`              |
 | `instruction` | Raw instruction text for the agent                           |
 
 ### KnowledgeSource
 
-Describes the origin of documentation content (a git repository URL ending
-in `.git`). The `@codemcp/knowledge` package manages the physical docset
-artifacts via its programmatic API (`createDocset` + `initDocset`); ADE
-tracks the sources in LogicalConfig.
+Describes the origin of documentation content. The `preset` field controls
+how the source is fetched: `"git-repo"` (default) for git repositories,
+`"archive"` for remote `.tar.gz` archives, `"local-folder"` for local paths.
+The `@codemcp/knowledge` package manages the physical docset artifacts via
+its programmatic API (`createDocset` + `initDocset`); ADE tracks the sources
+in LogicalConfig.
 
 ### LogicalConfig (intermediate representation)
 
@@ -95,7 +96,7 @@ resolution step and the agent writers:
 mcp_servers:        [{ref, command, args, env}]
 instructions:       [string]
 skills:             [SkillDefinition]
-knowledge_sources:  [{name, origin, description}]
+knowledge_sources:  [{name, origin, description, preset?}]
 ```
 
 ### Agent Writer
@@ -124,8 +125,6 @@ choices:
   practices: # multi-select facet
     - conventional-commits
     - tdd-london
-excluded_docsets: # docsets the user opted out of
-  - tanstack-table-docs
 custom: # user-managed section (not touched by CLI)
   mcp_servers:
     - ref: custom-server
@@ -148,16 +147,12 @@ when a facet selection or catalog version is updated.
 ## CLI Commands
 
 ```
-ade setup          Interactive TUI: walk through facets, confirm docsets,
-                   write config.yaml + config.lock.yaml + agent files,
-                   install skills and knowledge sources.
+ade setup          Interactive TUI: walk through facets, write
+                   config.yaml + config.lock.yaml + agent files,
+                   install skills, prompt to initialize knowledge sources.
                    Re-running setup on an existing project pre-selects
                    previous choices as defaults. Warns if a previous
                    selection references an option no longer in the catalog.
-
-ade install        Apply config.lock.yaml → agent files + skills + knowledge.
-                   Non-interactive. Idempotent. Does not re-resolve — uses
-                   the lock file as-is.
 ```
 
 ## Catalog
@@ -190,8 +185,8 @@ Stack and framework conventions that shape the project structure.
 | `tanstack` | Full-stack conventions for TanStack (Router, Query, Form, Table) |
 
 Each architecture option carries inline skills (conventions, design patterns,
-code style, testing) and recommended docsets (git repos for each library's
-documentation).
+code style, testing) and docset provisions (one `docset` recipe entry per
+documentation source).
 
 ### 3. Practices (`practices`) — multi-select
 
@@ -204,18 +199,20 @@ Composable development practices. Multiple selections allowed.
 | `adr-nygard`           | Architecture Decision Records following Nygard's template          |
 
 Practices with associated documentation (e.g. Conventional Commits) carry
-docsets that are collected alongside architecture docsets.
+`docset` provisions that resolve to knowledge sources alongside architecture
+docsets.
 
 ### Documentation Layer (derived)
 
 Documentation is **not** a standalone facet. Instead, each option in
-architecture and practices declares recommended `docsets[]`. The setup TUI
-collects all implied docsets and presents them as an opt-out confirmation
-step. Accepted docsets become `knowledge_sources` in LogicalConfig, which
-triggers:
+architecture and practices declares documentation sources as `docset`
+provisions in its recipe — the same mechanism used for skills. The resolver
+processes these like any other provision: `docsetWriter` maps each to a
+`KnowledgeSource`. Accepted docsets become `knowledge_sources` in
+LogicalConfig, which triggers:
 
 1. Automatic addition of the `@codemcp/knowledge-server` MCP server entry
-2. Installation via `@codemcp/knowledge` API (`createDocset` + `initDocset`)
+2. A confirmation prompt in `ade setup` — default is to defer initialization
 
 ## Non-Goals (initial release)
 
@@ -243,9 +240,10 @@ triggers:
 5. **User edits are confined to `custom`.** The rest of `config.yaml` is
    CLI-managed, eliminating merge conflicts in the structured sections.
 
-6. **Docsets are a weak entity on Option, not a separate facet.** Documentation
-   sources are always implied by an upstream selection. Making documentation a
-   standalone facet would create a hollow indirection whose options just mirror
-   upstream choices 1:1. Config stores `excluded_docsets` (what the user opted
-   out of) rather than selected docsets, keeping the common case (accept all
-   recommendations) zero-config.
+6. **Docsets are `docset` provisions in the recipe, not a separate field.**
+   Documentation sources are always implied by an upstream selection. They are
+   declared as `{ writer: "docset", config: {...} }` recipe entries —
+   consistent with how skills are declared. This eliminates the separate
+   `Option.docsets[]` field, the `excluded_docsets` opt-out mechanism, and the
+   per-item confirmation multiselect. Users can still defer or skip
+   initialization via the single confirm prompt in `ade setup`.