itseffi · itseffi · Aug 5, 2026 · Aug 5, 2026
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ No UI. No lock-in. Your agent does the thinking; Productize runs the lifecycle.
 
 ```bash
 npm install -g @productize/cli   # or: brew install --cask itseffi/productize/productize
-productize setup                 # install the skill catalog into your agent
+productize onboard existing --agent codex   # integrate an existing repository
 ```
 
 ---
@@ -21,7 +21,7 @@ productize setup                 # install the skill catalog into your agent
 
 A coding prompt gets you a diff. Shipping a product needs the work to hold together across many runs and many agents. Productize makes the *process* a first-class artifact:
 
-- **A repeatable lifecycle** — `init existing → create-prd → create-techspec → create-tasks → run → review → archive`, each stage producing a versioned file under `.productize/`.
+- **A repeatable lifecycle** — `onboard existing → create-prd → create-techspec → create-tasks → run → review → archive`, each stage producing a versioned file under `.productize/`.
 - **Works with the agent you have** — Claude Code, Codex, Cursor, Droid, OpenCode, Gemini, Copilot, and Pi. Pick per-run with `--ide` and `--model`.
 - **Skills, not prompts** — a large catalog of reusable skills and review gates, installed once and invoked by name inside your editor.
 - **Headless orchestration** — a background daemon runs tasks and review-fix loops over the Agent Client Protocol (ACP), so long jobs survive your terminal and can be reattached and replayed.
@@ -44,34 +44,30 @@ brew install --cask itseffi/productize/productize
 go install github.com/itseffi/productize/cmd/productize@latest
 ```
 
-### 2. Install the skills into your agent
+### 2. Onboard an existing project
 
 ```bash
-productize setup --agent codex
+productize onboard existing --agent codex
 ```
 
-`setup` installs the skill catalog into the agent/editor you choose — it supports **40+ agents and editors** (Claude Code, Codex, Cursor, Droid, OpenCode, Pi, Gemini, Copilot, Windsurf, Amp, Continue, Goose, Roo Code, Cline, and more). Non-interactive installs require an explicit target so Productize does not spray `.claude`, `.agents`, `.codex`, or other tool directories without permission. Installing skills is separate from *executing* through a runtime: to run `tasks run`, `reviews fix`, or `exec` you need an ACP-capable runtime (see the table below). Common options:
+`onboard existing` finds the repository root, inventories packages and existing
+project documentation, generates durable knowledge under `.productize/project/`,
+installs Productize for the selected agent, and registers the workspace. It is
+deterministic and does not call a model. Preview everything without mutations:
 
 ```bash
-productize setup --list            # show everything that would be installed
-productize setup --doctor --agent codex --format json
-productize setup --core-only       # install only the core lifecycle skills
-productize setup --global          # install for all projects (~/.productize) instead of just this one
-productize setup --agent claude --agent codex --yes
-productize setup --all-agents --yes
+productize onboard existing --agent codex --dry-run
 ```
 
-### 3. Adopt existing project context
-
-For an existing repo, generate durable project knowledge before asking an agent to plan new work:
+For a new repository, or when you want to manage installation separately, use
+the lower-level setup command:
 
 ```bash
-productize init existing
+productize setup --agent codex
+productize setup --agent claude --agent codex --yes
 ```
 
-This refreshes five generated read models under `.productize/project/`: `context.md`, `conventions.md`, `architecture.md`, `decisions.md`, and `constraints.md`. The command is deterministic and does not call a model. Put human-authored project guidance in `.productize/project/manual.md`; refreshes never own that file.
-
-### 4. Run the lifecycle
+### 3. Run the lifecycle
 
 Inside your AI agent (e.g. Claude Code), invoke the lifecycle skills in order. Each writes its output under `.productize/tasks/<slug>/`:
 
@@ -152,7 +148,10 @@ read models. Productize owns files carrying its `productize:project-knowledge`
 marker and leaves unmarked files untouched. Keep deliberate human-authored
 additions in `manual.md` so refreshes never compete with edits.
 
-- `productize init existing` creates or explicitly refreshes project knowledge.
+- `productize onboard existing` performs the complete first-time integration for
+  an existing repository.
+- `productize init existing` is the lower-level command for creating or explicitly
+  refreshing project knowledge without installing skills or registering a workspace.
 - A successful `productize sync` reconciles workflow artifacts into
   `~/.productize/db/global.db` and refreshes project knowledge from relevant
   repository facts, ADRs, and durable shared workflow memory.
@@ -163,7 +162,8 @@ additions in `manual.md` so refreshes never compete with edits.
 Knowledge refresh is a derived-read-model step. A sync or archive can complete
 while the refresh result is marked `degraded`; text output prints every skipped
 file and warning, and JSON exposes the optional `project_knowledge` object with
-`updated`, `unchanged`, `skipped`, `warnings`, `source_checksum`, and `degraded`.
+`updated`, `unchanged`, `skipped`, `warnings`, `source_checksum`, `degraded`,
+`inventory`, `diagnostics`, and `imported_repository_adrs`.
 Run `productize sync` again after resolving the warning to repair stale knowledge.
 
 ### ACP runtimes (execution backends)
@@ -199,7 +199,8 @@ productize runs watch <run-id>     # stream a running job
 
 | Command | What it does |
 |---------|--------------|
-| `productize init existing` | Adopt an existing repo into `.productize/project/` knowledge docs. |
+| `productize onboard existing` | Inventory an existing repo, generate knowledge, install skills, and register the workspace. |
+| `productize init existing` | Create or refresh only `.productize/project/` knowledge docs. |
 | `productize setup` | Install the skill catalog and reusable agents into your AI agent(s). |
 | `productize setup --doctor` | Inspect setup targets, paths, and drift without installing. |
 | `productize exec [prompt]` | Run one ad-hoc prompt through an ACP runtime (headless). |

diff --git a/agents/productize-operator/AGENT.md b/agents/productize-operator/AGENT.md
@@ -12,7 +12,8 @@ next safe Productize workflow action.
 
 Always inspect existing context before recommending a route:
 
-1. Read `.productize/project/context.md` when it exists.
+1. Read `.productize/project/context.md` when it exists, including its generated
+   Knowledge Coverage section and unresolved findings.
 2. Read `.productize/project/conventions.md` when it exists.
 3. Read `.productize/project/architecture.md` when it exists.
 4. Read `.productize/project/decisions.md` when it exists.
@@ -27,8 +28,9 @@ Always inspect existing context before recommending a route:
 
 For `/productize build <request>` or `build <request>`:
 
-- If `.productize/project/context.md` is missing, route first to
-  `productize init existing`.
+- If `.productize/project/context.md` is missing, degraded, stale, or reports
+  unresolved Knowledge Coverage findings, route first to
+  `productize onboard existing`.
 - If project context exists but PRD, TechSpec, or task files are missing, route
   through `/create-prd`, `/create-techspec`, then `/create-tasks`.
 - If task files exist, route to `productize tasks run <workflow>`.

diff --git a/docs/cli-reference.md b/docs/cli-reference.md
@@ -2,6 +2,49 @@
 
 This page keeps the long command tables out of the root README.
 
+## `productize onboard existing`
+
+Integrate Productize into a repository that already contains code and project
+knowledge.
+
+```bash
+productize onboard existing [path] [flags]
+```
+
+The command resolves the project root, inventories packages and existing
+documentation, generates canonical project knowledge, installs Productize for
+the selected agent, and registers the workspace. It is deterministic and does
+not invoke an AI model.
+
+| Flag | Default | Description |
+| ---- | ------- | ----------- |
+| `--agent`, `-a` | | Target agent/editor name; repeatable |
+| `--all-agents` | `false` | Install into every supported agent/editor destination |
+| `--global`, `-g` | `false` | Install skills in user scope instead of project scope |
+| `--copy` | `false` | Copy installed assets instead of symlinking |
+| `--core-only` | `false` | Install only core workflow skills |
+| `--no-tactical` | `false` | Compatibility alias for `--core-only` |
+| `--skip-setup` | `false` | Generate knowledge without installing agent assets |
+| `--skip-register` | `false` | Do not start the daemon or register the workspace |
+| `--name` | | Display name used for first workspace registration |
+| `--exclude` | | Repository-relative scan exclusion; repeatable |
+| `--dry-run` | `false` | Preview every step without mutations or daemon startup |
+| `--force` | `false` | Replace unmarked canonical knowledge targets only |
+| `--yes`, `-y` | `false` | Approve the complete non-interactive plan |
+| `--format` | `text` | Output format: `text` or `json` |
+
+Results use `ready`, `needs_review`, or `blocked`. JSON output is versioned and
+includes root-resolution evidence, inventory coverage, per-step results,
+structured diagnostics, and exact next actions. Use `productize init existing`
+when only the generated knowledge needs to be refreshed.
+
+JSON uses `schema_version: 1` with `workspace_root`, `root_resolution`,
+`inventory`, `knowledge`, `setup`, `workspace_registration`, `diagnostics`, and
+`next_actions`. Step statuses are `planned`, `current`, `changed`, `skipped`,
+`needs_review`, or `failed`. Exit code `0` means ready or a feasible dry-run;
+`1` means invalid selection, protection, or required review; `2` means an
+operational or output failure.
+
 ## `productize init existing`
 
 Adopt a mature repository into Productize project knowledge.
@@ -17,6 +60,7 @@ creating PRDs, TechSpecs, or tasks in an existing codebase.
 | Flag | Default | Description |
 | ---- | ------- | ----------- |
 | `--dry-run` | `false` | Preview generated project knowledge without writing files |
+| `--exclude` | | Repository-relative scan exclusion; repeatable |
 | `--force` | `false` | Overwrite existing unmarked project knowledge files |
 | `--format` | `text` | Output format: `text` or `json` |
 
@@ -113,7 +157,8 @@ productize sync [flags]
 Text output reports project knowledge as `current` or `degraded`, followed by
 the source checksum and any updated, unchanged, skipped, or warning entries.
 JSON includes the optional `project_knowledge` object with `updated`,
-`unchanged`, `skipped`, `warnings`, `source_checksum`, and `degraded`. If refresh
+`unchanged`, `skipped`, `warnings`, `source_checksum`, `degraded`, `inventory`,
+`diagnostics`, and `imported_repository_adrs`. If refresh
 is degraded, resolve its warnings and run `productize sync` again to retry.
 
 ## `productize daemon`

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -67,8 +67,18 @@ auto_push = false
 default_attach_mode = "stream"
 keep_terminal_days = 30
 keep_max = 500
+
+[project_knowledge]
+exclude = ["fixtures/generated/", "examples/vendor/**"]
+max_entries = 250000
+max_source_bytes = 1048576
+max_section_bytes = 8192
+max_document_bytes = 262144
 ```
 
+`max_document_bytes` must be at least 256 bytes so the generated ownership
+marker remains intact across refreshes.
+
 ## Supported Sections
 
 - `[defaults]` for shared execution defaults such as `ide`, `model`,
@@ -90,6 +100,9 @@ keep_max = 500
 - `[runs]` for `default_attach_mode`, `keep_terminal_days`, `keep_max`, and
   `shutdown_drain_timeout`
 - `[sound]` for optional run-completion audio presets or absolute file paths
+- `[project_knowledge]` for repository-relative scan exclusions and deterministic
+  inventory/source/document limits used by `onboard existing`, `init existing`,
+  sync, and archive knowledge refreshes
 
 ## Notes
 

diff --git a/docs/reusable-agents.md b/docs/reusable-agents.md
@@ -135,9 +135,10 @@ productize exec --agent productize-operator "build X"
 ```
 
 Productize ships `productize-operator` as the default reusable agent for driving
-the workflow. It reads project knowledge, inspects workflow artifacts, selects the
-next Productize route, and asks for approval before file writes, agent runs, or git
-changes.
+the workflow. It reads project knowledge and its Knowledge Coverage status,
+routes missing or degraded context through `productize onboard existing`, inspects
+workflow artifacts, selects the next Productize route, and asks for approval before
+file writes, agent runs, or git changes.
 
 Example `inspect` output (paths omitted):
 

diff --git a/docs/workflow.md b/docs/workflow.md
@@ -3,7 +3,7 @@
 Productize turns AI-assisted development into a repeatable pipeline. Each stage produces a versioned artifact under `.productize/tasks/<slug>/`, so the process is reviewable, resumable, and reproducible.
 
 ```
-init existing ─▶ idea ─▶ create-prd ─▶ create-techspec ─▶ create-tasks ─▶ tasks run ─▶ reviews fetch/fix/watch ─▶ archive
+onboard existing ─▶ idea ─▶ create-prd ─▶ create-techspec ─▶ create-tasks ─▶ tasks run ─▶ reviews fetch/fix/watch ─▶ archive
                           └────────── inside your AI agent ──────────┘    └──────────── productize CLI + daemon ────────────┘
 ```
 
@@ -14,15 +14,21 @@ The split matters:
 
 ---
 
-## 0. Adopt an existing project
+## 0. Onboard an existing project
 
-For mature repositories, start by generating durable project knowledge:
+For an existing repository, start with the complete integration workflow:
 
 ```bash
-productize init existing
+productize onboard existing --agent codex
 ```
 
-This scans repository facts without invoking an AI model and writes:
+This finds the project root, inventories existing packages and documentation,
+generates project knowledge, installs Productize for the selected agent, and
+registers the workspace. It is deterministic and does not invoke an AI model.
+Use `--dry-run` to preview the complete operation without writing files,
+installing assets, or starting the daemon.
+
+The knowledge step writes:
 
 ```
 .productize/project/
@@ -42,7 +48,8 @@ and task-execution workflows read all five canonical files when present, plus
 to understand feasibility and constraints, not to leak implementation details
 into business artifacts.
 
-`productize init existing` explicitly refreshes these read models. A successful
+`productize init existing` remains available as the lower-level knowledge-only
+refresh command. A successful
 `productize sync` also refreshes them after cataloging on-disk workflow artifacts,
 and `productize archive` refreshes them after moving the workflow so durable ADRs
 and shared memory survive archival. Use `--dry-run` to preview adoption output;
@@ -51,17 +58,18 @@ Productize ownership.
 
 ---
 
-## 1. Install the skills
+## Alternative for new repositories: install skills manually
 
 ```bash
 productize setup
 ```
 
-This puts the lifecycle skills into your agent. You only do it once per project (or `--global` once per machine).
+This lower-level command is useful for new repositories or when setup must be
+managed separately. `onboard existing` already performs project-scoped setup.
 
 ---
 
-## 2. PRD — `create-prd`
+## 1. PRD — `create-prd`
 
 Invoke `create-prd` in your agent with a feature name (and optionally an idea file). The skill drives codebase + web research, asks you clarifying questions, and explores multiple product approaches before writing:
 
@@ -71,15 +79,15 @@ Invoke `create-prd` in your agent with a feature name (and optionally an idea fi
 └── adrs/            # architecture/decision records captured along the way
 ```
 
-## 3. Tech spec — `create-techspec`
+## 2. Tech spec — `create-techspec`
 
 `create-techspec` reads the PRD and produces the technical design:
 
 ```
 .productize/tasks/<slug>/_techspec.md
 ```
 
-## 4. Task breakdown — `create-tasks`
+## 3. Task breakdown — `create-tasks`
 
 `create-tasks` decomposes the tech spec into an ordered, metadata-rich task list:
 
@@ -97,7 +105,7 @@ productize tasks validate
 
 ---
 
-## 5. Execute — `productize tasks run`
+## 4. Execute — `productize tasks run`
 
 ```bash
 productize tasks run <slug>
@@ -111,7 +119,7 @@ The daemon executes each task by driving your chosen agent over ACP. Useful flag
 
 ---
 
-## 6. Review & remediate — `productize reviews`
+## 5. Review & remediate — `productize reviews`
 
 Once you open a PR and a reviewer (human or a bot like CodeRabbit) leaves feedback:
 
@@ -133,7 +141,7 @@ productize reviews watch <slug> --until-clean --auto-push
 
 ---
 
-## 7. Archive
+## 6. Archive
 
 When a workflow is fully complete: