@codemcp/ade 0.7.0 → 0.8.0

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`.

package/docs/CLI-design.md

@@ -31,7 +31,7 @@ core/src/
   writers/              # built-in provision writers
     workflows.ts
     skills.ts
-    knowledge.ts
+    docset.ts
     instruction.ts
   agents/               # built-in agent writers
     claude-code.ts      # AGENTS.md, .claude/settings.json, skill files
@@ -91,21 +91,18 @@ read existing config.yaml (if any) for default selections
       → pre-select previous choice as default (if still valid)
       → warn if previous choice references a stale option
       → collect new user choices
-  → collect docsets from all selected options
-  → present docset confirmation (opt-out multiselect)
   → resolve choices + catalog → LogicalConfig
   → write config.yaml (user choices)
   → write config.lock.yaml (resolved LogicalConfig snapshot)
   → run agent writer (generate AGENTS.md, settings.json, etc.)
   → install skills via @codemcp/skills API
-  → install knowledge via @codemcp/knowledge API
+  → prompt to initialize knowledge sources via @codemcp/knowledge API
 ```
 
 Resolution expands each selected option's recipe provisions into
-LogicalConfig fragments, deduplicates docsets by id, filters by
-`excluded_docsets`, maps enabled docsets to `knowledge_sources`, adds the
-`@codemcp/knowledge-server` MCP entry if knowledge sources are present,
-merges the custom section, and deduplicates MCP servers by ref.
+LogicalConfig fragments, maps `docset` provisions to `knowledge_sources`,
+adds the `@codemcp/knowledge-server` MCP entry if knowledge sources are
+present, merges the custom section, and deduplicates MCP servers by ref.
 
 For **multi-select facets**, each selected option's recipe is resolved
 independently and their LogicalConfig fragments are merged.
@@ -180,23 +177,6 @@ interface Option {
   label: string; // e.g. "CodeMCP Workflows"
   description: string;
   recipe: Provision[]; // multiple provisions per option is common
-  docsets?: DocsetDef[]; // recommended documentation for this option
-}
-
-// Documentation as a weak entity on Option. Docsets are derived from
-// upstream selections — picking "TanStack" in architecture implies
-// TanStack docs, picking "GitHub Actions CI/CD" in practices implies
-// GH Actions docs. The TUI presents all implied docsets as pre-selected
-// defaults and allows the user to deselect. This is opt-out, not opt-in.
-//
-// The resolver collects docsets from all selected options, deduplicates
-// by id, filters by excluded_docsets from UserConfig, and maps enabled
-// docsets directly to knowledge_sources in LogicalConfig.
-interface DocsetDef {
-  id: string; // unique key for dedup, e.g. "tanstack-query-docs"
-  label: string; // display name, e.g. "TanStack Query Reference"
-  origin: string; // URL, path, or package ref
-  description: string; // shown in TUI
 }
 
 // A recipe typically contains multiple provisions for different writers.
@@ -238,6 +218,7 @@ interface KnowledgeSource {
   name: string; // e.g. "tanstack"
   origin: string; // URL, path, or package ref
   description: string;
+  preset?: "git-repo" | "local-folder" | "archive"; // defaults to "git-repo"
 }
 ```
 
@@ -247,7 +228,6 @@ interface KnowledgeSource {
 // config.yaml — mostly CLI-managed, agent-agnostic
 interface UserConfig {
   choices: Record<string, string | string[]>; // single-select: string, multi-select: string[]
-  excluded_docsets?: string[]; // docset IDs the user opted out of
   custom?: {
     // user-managed section
     mcp_servers?: McpServerEntry[];
@@ -355,7 +335,7 @@ function createDefaultRegistry(): WriterRegistry {
   registerProvisionWriter(registry, instructionWriter);
   registerProvisionWriter(registry, workflowsWriter);
   registerProvisionWriter(registry, skillsWriter);
-  registerProvisionWriter(registry, knowledgeWriter);
+  registerProvisionWriter(registry, docsetWriter);
 
   registerAgentWriter(registry, claudeCodeWriter);
 
@@ -390,10 +370,12 @@ interface SkillsConfig {
   skills: SkillDefinition[];
 }
 
-interface KnowledgeConfig {
-  name: string;
-  origin: string; // must be a valid .git URL
+interface DocsetConfig {
+  id: string;
+  label: string;
+  origin: string;
   description: string;
+  preset?: "git-repo" | "local-folder" | "archive"; // defaults to "git-repo"
 }
 
 interface InstructionConfig {
@@ -474,16 +456,23 @@ Inline skills include a `body` field; external skills reference a `source`.
 The actual installation (writing SKILL.md files and calling `@codemcp/skills`
 API) is handled by the agent writer and CLI's `skills-installer`.
 
-### `knowledge` writer
+### `docset` writer
 
 ```typescript
-{ name: "tanstack-query-docs", origin: "https://github.com/TanStack/query.git", description: "Server state management" }
+{
+  id: "tanstack-query-docs",
+  label: "TanStack Query",
+  origin: "https://github.com/TanStack/query.git",
+  description: "Server state management",
+  preset: "git-repo" // optional, defaults to "git-repo"
+}
 ```
 
-Produces a `KnowledgeSource` entry in LogicalConfig. The actual installation
-(calling `@codemcp/knowledge` API) is handled by the CLI's
-`knowledge-installer`. Origins must be valid `.git` URLs for the `git-repo`
-preset.
+Produces a `KnowledgeSource` entry in LogicalConfig. 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 actual installation (calling `@codemcp/knowledge` API)
+is handled by the CLI's `knowledge-installer`.
 
 ### `mcp-server` writer
 
@@ -545,7 +534,7 @@ export const processFacet: Facet = {
   ]
 };
 
-// catalog/facets/architecture.ts — options carry skills + docsets
+// catalog/facets/architecture.ts — options carry skills + docset provisions
 export const architectureFacet: Facet = {
   id: "architecture",
   label: "Architecture",
@@ -578,20 +567,24 @@ export const architectureFacet: Facet = {
         {
           writer: "instruction",
           config: { text: "This project follows TanStack conventions..." }
-        }
-      ],
-      docsets: [
+        },
         {
-          id: "tanstack-router-docs",
-          label: "TanStack Router",
-          origin: "https://github.com/TanStack/router.git",
-          description: "File-based routing, loaders, and search params"
+          writer: "docset",
+          config: {
+            id: "tanstack-router-docs",
+            label: "TanStack Router",
+            origin: "https://github.com/TanStack/router.git",
+            description: "File-based routing, loaders, and search params"
+          }
         },
         {
-          id: "tanstack-query-docs",
-          label: "TanStack Query",
-          origin: "https://github.com/TanStack/query.git",
-          description: "Server state management, caching, and mutations"
+          writer: "docset",
+          config: {
+            id: "tanstack-query-docs",
+            label: "TanStack Query",
+            origin: "https://github.com/TanStack/query.git",
+            description: "Server state management, caching, and mutations"
+          }
         }
         // ... form, table
       ]
@@ -634,13 +627,10 @@ export const architectureFacet: Facet = {
    merge conflicts: the CLI never touches `custom`, and users never touch
    the rest. Agent writers merge both sections when generating output.
 
-7. **Docsets are a weak entity on Option, not a separate facet.** Documentation
-   sources are always implied by an upstream selection (architecture or
-   practices). Making documentation a standalone facet would create a hollow
-   indirection whose options just mirror upstream choices 1:1. Instead, each
-   `Option` declares its recommended `docsets[]`. The resolver collects and
-   deduplicates them; the TUI presents them as a confirmation step (opt-out,
-   not opt-in). Config stores `excluded_docsets` (what the user opted out of)
-   rather than selected docsets, keeping the common case (accept all
-   recommendations) zero-config. When knowledge sources are present, the
+7. **Docsets are `docset` provisions in the recipe, not a separate field on Option.**
+   Documentation sources are always implied by an upstream selection (architecture
+   or practices). Each option declares docsets as `{ writer: "docset", config: {...} }`
+   recipe entries — consistent with how skills are declared. The resolver processes
+   `docset` provisions like any other: the `docsetWriter` maps each one to a
+   `KnowledgeSource` in LogicalConfig. When knowledge sources are present, the
    resolver automatically adds a `@codemcp/knowledge-server` MCP server entry.

package/docs/guide/extensions.md

@@ -89,21 +89,14 @@ export default {
             }
           },
           {
-            writer: "knowledge",
+            writer: "docset",
             config: {
-              name: "sap-abap-docs",
-              origin: "https://help.sap.com/docs/abap-cloud",
-              description: "SAP ABAP Cloud documentation"
+              id: "sap-abap-cloud-docs",
+              label: "SAP ABAP Cloud",
+              origin: "https://your-serialized-version-of-abap-docs.git",
+              description: "SAP ABAP Cloud development documentation"
             }
           }
-        ],
-        docsets: [
-          {
-            id: "sap-abap-cloud-docs",
-            label: "SAP ABAP Cloud",
-            origin: "https://help.sap.com/docs/abap-cloud",
-            description: "SAP ABAP Cloud development documentation"
-          }
         ]
       }
     ]
@@ -117,8 +110,7 @@ After running `ade setup` and selecting `SAP BTP / ABAP`:
   to `.agentskills/skills/<name>/` for agent consumption
 - Knowledge sources appear in `config.lock.yaml` under
   `logical_config.knowledge_sources` and can be initialised with
-  `npx @codemcp/knowledge init`
-- Docsets appear in the setup wizard's documentation sources step
+  `npx @codemcp/knowledge init <id>`
 
 ## Adding a new facet
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/ade",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "ADE CLI — Agentic Development Environment setup and configuration tool",
   "license": "MIT",
   "keywords": [