@contextium/cli 1.0.14 → 1.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextium/cli",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "Command-line tool for managing Contextium documentation, agents, skills, and workflows — pipe context to AI coding assistants",
   "keywords": [
     "contextium",

package/skills/ium/contextium.md

@@ -49,6 +49,32 @@ Workspace
 | A role combining multiple skills? | Agent |
 | Ready-to-use context package for a task? | Workflow |
 
+## Contextium Is the Source of Truth
+
+All AI-relevant information — project state, SOPs, constraints, decisions, research, planning — lives in Contextium. It is always written to Contextium first. Local files are only for things that belong in git: source code, config, READMEs.
+
+Never write AI planning or knowledge files locally by default. If a user specifically asks for a local copy of something, write it — but Contextium is always written first and is always authoritative.
+
+This gives users something local file-based tools cannot: state survives machine loss, team members share the same context, and multiple projects run in parallel — one workflow loaded per terminal session — with no interference between them.
+
+## Multi-Project Rule
+
+Each project must have its own dedicated context library. Never mix two projects into one library.
+
+The project state file (`project-state.md`) is the single source of truth for a project's current position, locked decisions, and seeds. **Only one `project-state.md` should ever exist per library.** If a second one would need to be created in the same library, stop and ask the user to use a different library or create a new one.
+
+## Decision Routing
+
+When a significant architectural, technical, or approach decision is made during any session, write it to the `## Decisions Log` in `project-state.md` immediately — no user permission needed. Log it silently and mention it in the phase summary.
+
+A decision qualifies if it:
+- Picks a technology or library
+- Sets an API contract or data model
+- Establishes a pattern future phases will depend on
+- Rules out an approach that was considered
+
+Decisions in the log are **locked**. Future sessions must not re-debate them. If the user explicitly wants to revisit a decision, they must say so — only then update the entry.
+
 ## File Routing — Writing Files When Contextium Is Connected
 
 When the Contextium MCP is connected or the CLI is active, **any time a new file is about to be created**, intercept it with a routing question before writing:

package/skills/ium/help.md

@@ -17,6 +17,10 @@ Output the following help reference directly — no tools needed:
 ╚══════════════════════════════════════════════════════════════╝
 
 GETTING STARTED
+  /ium:scan-existing   Scan an existing codebase and write analysis docs to
+                       Contextium — stack, architecture, conventions, concerns.
+                       Run this before /ium:new-project on existing projects.
+
   /ium:new-project     Set up a new Contextium project from scratch —
                        auth, workspace, libraries, agents, skills, workflow
 

package/skills/ium/new-project.md

@@ -92,6 +92,19 @@ If yes:
 If no: continue to project description with a clean slate.
 </step>
 
+<step name="codebase_scan_check">
+Silently check whether any library in the selected workspace contains codebase analysis documents from `/ium:scan-existing`. Look for files named `stack.md`, `architecture.md`, `structure.md`, `conventions.md`, `concerns.md` in any library.
+
+**CLI:** `contextium library list --workspace <slug> 2>/dev/null` then check file lists per library
+**MCP:** call mcp__contextium__list_context_libraries, then mcp__contextium__list_files for each
+
+If found, read `architecture.md` and `stack.md` silently to understand what already exists. Store this as `has_codebase_scan = true` and `codebase_library = <library name>`. This will be used later to pre-populate validated capabilities in the project state.
+
+If not found, set `has_codebase_scan = false` and continue.
+
+Do not mention this check to the user.
+</step>
+
 <step name="project_description">
 Ask the user this question exactly:
 
@@ -202,7 +215,7 @@ If no: set `research_agent_planned = false` and continue.
 <step name="planner_question">
 Ask the user:
 
-"Would you like a project planner to break your project into phases and track progress? I'll create a planning agent and a phase tracker document you can follow from start to finish."
+"Would you like a project planner to break your project into phases and track progress? I'll create a planning agent and a state document you can follow from start to finish."
 
 Use AskUserQuestion:
 - "Yes, add a project planner"
@@ -210,23 +223,59 @@ Use AskUserQuestion:
 
 If yes:
 1. Add a "**[Project Name] Planner**" agent to the creation plan — its role is to define project phases, estimate scope, and guide execution in order. Tailor its system prompt to the project domain. Store as `planner_planned = true`.
-2. After all resources are created, create a planning document file in the most relevant library. The file should contain a phased breakdown of the project inferred from the user's description — structured like:
+2. After all resources are created, create a project state document in the most relevant library. This is the living memory for the project — not just a phase list. Use this exact structure:
 
 ```markdown
-# [Project Name] — Project Plan
+# [Project Name] — Project State
 
-## Phase 1: [Name]
+## Current Position
+**Phase:** Phase 1: [Name]
+**Status:** Not Started
+**Last Updated:** [today's date]
+**Next Action:** Begin Phase 1
+
+## Already Built
+> Capabilities confirmed by codebase scan — these do not need to be built.
+> _(Remove this section if starting a greenfield project with no existing code)_
+
+- ✓ [Existing capability — e.g. "Express API with JWT auth"] — `src/server.ts`
+- ✓ [Existing capability] — `src/`
+
+## Phases
+
+### Phase 1: [Name]
 **Status:** Not Started
 [Brief description of what this phase covers]
 
-## Phase 2: [Name]
+### Phase 2: [Name]
 **Status:** Not Started
 [Brief description]
 
 ...
+
+## Decisions Log
+> Locked decisions — record here when a significant architectural, technical, or approach decision is made. Do not re-debate entries in this log.
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| _(none yet)_ | | |
+
+## Seeds
+> Ideas and suggestions to revisit at the right time — not immediate work.
+
+| Idea | When to revisit | Context |
+|------|-----------------|---------|
+| _(none yet)_ | | |
+
+## Notes
+_(ad-hoc notes that don't fit elsewhere)_
 ```
 
-Infer sensible phases from the project description. Use "Not Started" for all phases. Title the file something like `project-plan.md`.
+Infer sensible phases from the project description. Title the file `project-state.md`.
+
+**If `has_codebase_scan = true`:** populate the `## Already Built` section from the `architecture.md` found in the codebase scan library — list the key capabilities that clearly already exist. Only plan phases for what is **not** in the Already Built list. If starting greenfield, remove the Already Built section entirely.
+
+**Important:** Only one `project-state.md` should ever exist per context library. This is the single source of truth for this project. Never create a second one or split state across multiple files.
 
 If no: set `planner_planned = false` and continue.
 </step>
@@ -238,25 +287,17 @@ Do NOT create a workflow in this step.
 
 Show `✓ Created "Name"` for each item as it is created. Show `↗ Reusing "Name"` for each existing resource being included.
 
-If `planner_planned = true`, create the project plan file after all other resources are created:
+If `planner_planned = true`, create the project state file in Contextium after all other resources are created:
 
 **CLI:**
 ```bash
-cat << 'EOF' | contextium new <library-name> -t "[Project Name] — Project Plan" -p "project-plan.md" --stdin -w <workspace>
-<generated phase content>
+cat << 'EOF' | contextium new <library-name> -t "[Project Name] — Project State" -p "project-state.md" --stdin -w <workspace>
+<generated state content>
 EOF
 ```
-**MCP:** call mcp__contextium__create_file with the phase content.
+**MCP:** call mcp__contextium__create_file with the state content.
 
-Also write the same content locally to `.ium-planning/project-plan.md` so there is always a local fallback:
-
-```bash
-mkdir -p .ium-planning && cat << 'EOF' > .ium-planning/project-plan.md
-<same generated phase content>
-EOF
-```
-
-Show `✓ Created project plan "project-plan.md"` and `✓ Saved local backup to .ium-planning/project-plan.md` when done.
+Show `✓ Created project state "project-state.md"` when done.
 
 Suppress all errors silently — if something fails, skip it quietly and note it in the summary.
 
@@ -323,7 +364,7 @@ Use AskUserQuestion:
 - "Yes, start planning now"
 - "No, I'll do it later"
 
-If yes: activate the planner agent — instruct it to analyse the project description and produce a detailed phased plan, updating the `project-plan.md` file created earlier with specific tasks, milestones, and sequencing. Let it run and surface the plan to the user.
+If yes: activate the planner agent — instruct it to analyse the project description and produce a detailed phased plan, updating the `project-state.md` file created earlier with specific tasks, milestones, and sequencing. Let it run and surface the plan to the user.
 
 If no: continue to summary.
 </step>
@@ -364,16 +405,24 @@ If anything failed to create, add a single line at the end:
 These rules apply for the duration of the project, after setup is complete.
 
 **New suggestions and feature ideas**
-- Whenever a new feature, idea, or suggestion comes up during the project, ask: "Would you like to add this to the project plan to tackle after the current work is done?"
-- If yes: append it to `project-plan.md` as a new phase with status "Not Started"
+- Whenever a new feature, idea, or suggestion comes up during the project, ask: "Would you like to add this to the project state as a seed to revisit later?"
+- If yes: append it to the `## Seeds` section of `project-state.md` in Contextium with a "When to revisit" trigger (e.g. "When Phase 3 begins", "When load testing reveals bottlenecks") and a brief context note.
 - If no: note it and continue with the current work
-
-**Tackling a new feature or setting**
-- When the user is ready to start work on a new feature or area of the project, ask:
-  1. "Would you like to run a research phase on this first?" — if a research agent exists, use it; otherwise offer to create one
-  2. "Would you like a phased plan for this?" — if a planner agent exists, use it to produce a plan and add it to `project-plan.md`; otherwise offer to create one
-- If the user says no to both, continue directly using the existing agents based on their instructions — no extra setup needed
-- Treat each new feature as its own mini-project using the existing workspace resources — never create duplicate agents or skills if suitable ones already exist
+- Seeds are NOT immediate work — never promote a seed to a phase without the user asking
+
+**Decision locking**
+- Whenever a significant architectural, technical, or approach decision is made during a phase, write it to the `## Decisions Log` table in `project-state.md` in Contextium immediately.
+- A decision qualifies if it: picks a technology, sets an API contract, defines a data model, or establishes a pattern that future phases will depend on
+- Decisions in the log are **locked** — do not re-debate them in future sessions. If the user wants to revisit a decision, they must explicitly say so; only then remove or update the entry
+- Never ask the user's permission to log a decision — just do it silently and mention it in the phase summary
+
+**Tackling a new feature or phase**
+- When the user is ready to start work on a new feature or area of the project:
+  1. Update `## Current Position` in `project-state.md` in Contextium to reflect the new phase — set Phase, Status to "In Progress", and Next Action.
+  2. Ask: "Would you like to run a research phase on this first?" — if a research agent exists, use it; otherwise offer to create one
+  3. Ask: "Would you like a phased plan for this?" — if a planner agent exists, use it; otherwise offer to create one
+- If the user says no to both, continue directly using existing agents — no extra setup needed
+- Treat each new feature as its own mini-project using existing workspace resources — never create duplicate agents or skills if suitable ones already exist
 
 **Suggesting new agents and skills**
 - If the work the user is describing would clearly benefit from an agent or skill that doesn't exist yet, proactively suggest creating one — explain what it would do and why it would help
@@ -383,28 +432,27 @@ These rules apply for the duration of the project, after setup is complete.
 **Session usage check at end of every phase**
 - At the end of every completed phase, check the current session context usage (visible in the Claude Code status bar as a percentage)
 - If usage is **above 50%**, do the following automatically before prompting the user to continue:
-  1. Write a handoff note into `project-plan.md` under the current phase — mark it with the current status and add a `> Session Handoff` block containing: what was completed, what decisions were made, what the next phase requires, and any open questions. Write this update to **both** the Contextium library file and the local `.ium-planning/project-plan.md` file simultaneously so they stay in sync
-  2. Update the phase status to "In Progress" or "Complete" as appropriate in both locations
-  3. Tell the user:
+  1. Update `project-state.md` in Contextium — mark the phase "Complete" or "In Progress", update `## Current Position` to point to the next phase, and add a `> Session Handoff` block under the current phase containing: what was completed, decisions made this session (list them), what the next phase requires, and open questions.
+  2. Tell the user:
 
   ```
   ⚠ Session is above 50% — recommended to start a fresh session before the next phase.
 
-  A handoff note has been saved to your project plan.
+  Project state has been saved to your Contextium library.
   Run /ium:resume-project to pick up exactly where you left off.
   ```
 
-- If usage is **below 50%**, simply confirm the phase is complete and ask if the user is ready to move to the next phase
+- If usage is **below 50%**, confirm the phase is complete, update `## Current Position` to the next phase, and ask if the user is ready to move on
 - Never skip this check at phase end — even if the user seems eager to continue
 
-**Local project plan — hidden file**
-- The local project plan is stored at `.ium-planning/project-plan.md`. The `.ium-planning/` directory starts with a dot, making it hidden by default on macOS and Linux — it will not appear in Finder or standard terminal listings unless the user explicitly shows hidden files. This is intentional to reduce the chance of accidental deletion.
-- Never tell the user where the file is stored unless they ask — it is a background concern
+**Multi-project rule**
+- Only one `project-state.md` should ever exist per context library. If a user has multiple projects, each project must have its own dedicated library — never mix two projects' state into one library.
+- If a second `project-state.md` would need to be created in the same library, stop and ask the user to either use a different library or create a new one for this project.
 
 **Project completion — convert to product description**
-- When all phases in `project-plan.md` are marked "Complete", automatically trigger the following:
-  1. Ask the user: "All phases are complete — congratulations! Would you like me to convert the project plan into a Product Description document?"
-  2. If yes: rewrite the content of `project-plan.md` (both Contextium and local) as a clean Product Description — summarise what was built, the decisions made, the architecture or approach used, and any outcomes. Remove phase status markers. Title it "[Project Name] — Product Description". This document serves as a reference for future projects and prevents overlap.
-  3. If no: leave the plan as-is and congratulate the user
+- When all phases in `project-state.md` are marked "Complete", automatically trigger the following:
+  1. Ask the user: "All phases are complete — congratulations! Would you like me to convert the project state into a Product Description document?"
+  2. If yes: rewrite the content in Contextium as a clean Product Description — summarise what was built, the decisions made (draw from the Decisions Log), the architecture or approach used, and outcomes. Remove phase status markers and the Decisions Log table. Title it "[Project Name] — Product Description". This document serves as a reference for future projects.
+  3. If no: leave the state file as-is and congratulate the user
 - Never convert automatically without asking — always get confirmation first
 </ongoing-project-rules>

package/skills/ium/resume-project.md

@@ -34,72 +34,66 @@ Load the chosen workflow silently:
 **MCP:** call mcp__contextium__load_workflow
 </step>
 
-<step name="find_project_plan">
-Check for the project plan in this order:
+<step name="find_project_state">
+Contextium is the source of truth. Always read from there first.
 
-**1. Local first** — check for `.ium-planning/project-plan.md` in the current directory:
+**1. Contextium first** — search the loaded workflow's libraries for `project-state.md`:
 
-```bash
-cat .ium-planning/project-plan.md 2>/dev/null
-```
-
-If found locally, use it. Show `→ Using local project plan (.ium-planning/project-plan.md)` and skip the Contextium lookup.
-
-**2. Contextium fallback** — if not found locally, search the loaded workflow's libraries:
-
-**CLI:** `contextium find "project-plan" -w <workspace> 2>/dev/null`
-**MCP:** search list_files across the workflow's libraries for a file with path matching `project-plan.md`
+**CLI:** `contextium find "project-state" -w <workspace> 2>/dev/null`
+**MCP:** search list_files across the workflow's libraries for a file with path matching `project-state.md`
 
-If found in Contextium, fetch the full content:
+If found, fetch the full content:
 
 **CLI:** `contextium cat <fileId> -w <workspace> 2>/dev/null`
 **MCP:** call mcp__contextium__get_file with the file ID
 
-Then write it to `.ium-planning/project-plan.md` locally so future sessions have the local copy:
+**2. Legacy fallback** — if `project-state.md` is not found, search for the older `project-plan.md` filename in the same libraries and treat it the same way.
 
-```bash
-mkdir -p .ium-planning && cat << 'EOF' > .ium-planning/project-plan.md
-<fetched content>
-EOF
-```
-
-**3. Not found** — if the plan is in neither location, tell the user:
-"No project plan found locally or in your Contextium workspace. If you set up this project with `/ium:new-project`, the plan should be in `.ium-planning/project-plan.md` or in one of your libraries. Would you like me to search the full workspace?"
+**3. Not found** — if not found in Contextium, tell the user:
+"No project state found in your Contextium workspace. If you set up this project with `/ium:new-project`, the state should be in one of your libraries. Would you like me to search the full workspace?"
 </step>
 
-<step name="parse_handoff">
-Read the project plan and identify:
+<step name="parse_state">
+Read the project state file and extract:
 
-1. The **current phase** — the last phase marked "In Progress", or the first phase marked "Not Started" if none are in progress
-2. The **handoff note** — look for a `> Session Handoff` block under the current phase. This contains what was completed, decisions made, what's needed next, and open questions
+1. **Current Position** — from the `## Current Position` section: current phase name, status, and next action
+2. **Handoff note** — look for a `> Session Handoff` block under the current phase. Contains what was completed, decisions made, what's needed next, open questions
 3. **Completed phases** — all phases marked "Complete"
-4. **Remaining phases** — all phases still "Not Started"
+4. **Remaining phases** — all phases still "Not Started" or "In Progress"
+5. **Recent decisions** — the last 3 entries from the `## Decisions Log` table (if it exists and has entries)
+6. **Pending seeds** — any entries in the `## Seeds` table (surface only if relevant to the current phase)
 
 Present a clear resumption brief:
 
 ```
 ── Resuming: [Project Name] ──────────────────────
 
-Completed phases:
+Completed:
   ✓ Phase 1: [Name]
   ✓ Phase 2: [Name]
 
-Current phase:
+Current:
   → Phase 3: [Name] — In Progress
+  Next action: [from Current Position]
 
 Last session notes:
-  [Handoff note content]
+  [Handoff note content, or phase description if no handoff]
 
 Up next:
-  [What the handoff says needs to happen next]
+  [What the handoff says needs to happen]
 
-Remaining phases:
+Remaining:
   ○ Phase 4: [Name]
   ○ Phase 5: [Name]
 
+Locked decisions:
+  • [Decision] — [Rationale]
+  • [Decision] — [Rationale]
+
 ─────────────────────────────────────────────────
 ```
 
+Only show the "Locked decisions" section if the Decisions Log has entries — these are facts the session must not re-debate.
 If no handoff note exists under the current phase, summarise the phase description instead.
 </step>
 
@@ -113,21 +107,21 @@ Use AskUserQuestion:
 - "Give me a summary of what we're building first"
 - "I want to start a different phase"
 
-If "Yes, let's go": activate the appropriate agent(s) from the loaded workflow and begin the phase work. Update the phase status in `project-plan.md` to "In Progress" if it isn't already.
+If "Yes, let's go": activate the appropriate agent(s) from the loaded workflow and begin the phase work. Update the phase status in `project-state.md` to "In Progress" if it isn't already.
 
 If "Give me a summary": provide a concise overview of the full project and current phase goals drawn from the plan, then ask again if they're ready to continue.
 
-If "I want to start a different phase": list the available phases and let them pick one. Update that phase to "In Progress" in `project-plan.md`.
+If "I want to start a different phase": list the available phases and let them pick one. Update that phase to "In Progress" in `project-state.md`.
 </step>
 
 </process>
 
 <rules>
 - Never show raw file IDs, API responses, or CLI output to the user
-- Always load the workflow before reading the project plan — never search the full workspace without it
-- If the project plan has no handoff note, still resume gracefully using the phase description
-- When continuing work, always update phase status in `project-plan.md` to reflect current state — write to both Contextium and `.ium-planning/project-plan.md` simultaneously
-- At the end of each phase, follow the session usage check rule — if above 50%, write a new handoff note to both locations and prompt the user to start a fresh session with `/ium:resume-project`
-- The `.ium-planning/` directory is intentionally hidden (dot-prefixed) — never mention its location unless the user asks
-- If all phases are marked "Complete" when reading the plan, ask the user if they want to convert it into a Product Description document before resuming — do not start new phase work on a completed project without asking
+- Always load the workflow before reading the project state — never search the full workspace without it
+- If the state file has no handoff note, still resume gracefully using the phase description and Current Position
+- When continuing work, always update `## Current Position` and phase status in `project-state.md` in Contextium
+- Decisions in the `## Decisions Log` are locked — surface them in the resumption brief so the session starts with full context, but never re-debate them unless the user explicitly asks to
+- At the end of each phase, follow the session usage check rule — if above 50%, write a new handoff note and update Current Position in Contextium, then prompt the user to start a fresh session with `/ium:resume-project`
+- If all phases are marked "Complete" when reading the state, ask the user if they want to convert it into a Product Description document before resuming — do not start new phase work on a completed project without asking
 </rules>

package/skills/ium/scan-existing.md

@@ -0,0 +1,422 @@
+---
+name: ium:scan-existing
+description: Scan an existing codebase and write analysis documents to a Contextium context library — tech stack, architecture, structure, conventions, and concerns. Used before /ium:new-project to generate a roadmap that knows what's already built vs what still needs doing.
+allowed-tools:
+  - Bash
+  - Glob
+  - Grep
+  - Read
+  - mcp__contextium__list_workspaces
+  - mcp__contextium__list_context_libraries
+  - mcp__contextium__list_workflows
+  - mcp__contextium__load_workflow
+  - mcp__contextium__create_context_library
+  - mcp__contextium__create_file
+  - mcp__contextium__update_file
+  - mcp__contextium__list_files
+  - mcp__contextium__get_file
+  - AskUserQuestion
+---
+
+<objective>
+Analyse an existing codebase across five domains and write the findings as structured documents to a Contextium context library. The output gives any agent full context about what exists, how it's built, and what's already working — without re-analysing the codebase every session. When followed by /ium:new-project, the roadmap will know what's already done and only plan phases for what's missing.
+</objective>
+
+<mode-detection>
+Run once at the start, silently:
+
+```bash
+command -v contextium &>/dev/null && echo "cli" || echo "no-cli"
+```
+
+- If `cli`: use CLI commands throughout.
+- If `no-cli`: use MCP tools throughout.
+- If neither: tell the user "Contextium doesn't appear to be installed." and stop.
+</mode-detection>
+
+<process>
+
+<step name="check_auth">
+**CLI only.** Run silently:
+```bash
+contextium whoami 2>/dev/null | grep -E "Token:|Name:" || echo "unauthenticated"
+```
+If unauthenticated or token expired, tell the user to run `contextium login` and stop.
+
+MCP users are already authenticated — skip.
+</step>
+
+<step name="select_library">
+Determine where to write the codebase documents.
+
+If a workflow is already loaded in this session, check whether any of its libraries have an obvious "codebase" or "technical" purpose. If yes, suggest it. If not, ask which library to use.
+
+If no workflow is loaded:
+
+**CLI:** `contextium library list --workspace <slug> 2>/dev/null`
+**MCP:** call mcp__contextium__list_context_libraries
+
+Ask: "Which library should I write the codebase analysis to? Or I can create a new one — for example, 'Codebase Analysis'."
+
+Use AskUserQuestion:
+- Present existing library names
+- "Create a new library for this"
+
+If creating new: use the name the user provides, or default to "[Project Name] Codebase". Create it:
+
+**CLI:** `contextium library create "<name>" --workspace <slug>`
+**MCP:** call mcp__contextium__create_context_library
+
+Store the target library ID as `target_library_id`.
+</step>
+
+<step name="check_existing">
+Check whether any of the five analysis documents already exist in the target library by listing its files and looking for: `stack.md`, `architecture.md`, `structure.md`, `conventions.md`, `concerns.md`.
+
+If any exist, ask:
+
+"I found existing analysis documents in this library. What would you like to do?"
+
+Use AskUserQuestion:
+- "Refresh all documents (overwrite)"
+- "Update specific documents only"
+- "Cancel"
+
+If "Update specific": ask which ones to update. Only run analysis passes for those.
+If "Refresh all" or no existing docs: run all five passes.
+</step>
+
+<step name="orient">
+Before analysing, silently orient yourself to the project. Run:
+
+```bash
+ls -la 2>/dev/null | head -40
+```
+
+Then look for the project's primary language and framework indicators:
+
+```bash
+ls package.json requirements.txt Cargo.toml go.mod pyproject.toml composer.json 2>/dev/null
+```
+
+```bash
+ls -d src/ app/ lib/ pkg/ internal/ api/ 2>/dev/null
+```
+
+Do not show this output to the user. Use it to focus the analysis passes that follow.
+
+Tell the user:
+```
+Scanning codebase — this will take a moment.
+
+  ○ Tech stack & integrations
+  ○ Architecture & structure
+  ○ Conventions & testing
+  ○ Concerns & tech debt
+```
+
+Update each `○` to `✓` as each pass completes.
+</step>
+
+<step name="pass_1_tech">
+**Tech Stack & Integrations**
+
+Analyse and write `stack.md`:
+
+Read dependency manifests:
+```bash
+cat package.json 2>/dev/null
+cat requirements.txt pyproject.toml 2>/dev/null
+cat Cargo.toml go.mod 2>/dev/null
+cat composer.json 2>/dev/null
+```
+
+Read config files:
+```bash
+cat tsconfig.json 2>/dev/null
+ls *.config.* 2>/dev/null
+cat .nvmrc .node-version .python-version 2>/dev/null
+```
+
+Check for external service patterns:
+```bash
+grep -rn "process\.env\." src/ app/ lib/ 2>/dev/null | grep -v "node_modules" | head -40
+cat .env.example .env.sample 2>/dev/null
+```
+
+Produce `stack.md` in this structure:
+
+```markdown
+# Tech Stack
+**Analysis Date:** [today]
+
+## Runtime & Language
+[language, version, runtime]
+
+## Frameworks & Libraries
+[list key dependencies with versions and purpose]
+
+## Build & Tooling
+[build system, bundler, linter, formatter, type checker]
+
+## External Services & Integrations
+[APIs, databases, auth providers, storage, email — with env var names]
+
+## Platform & Deployment
+[inferred from config files — Docker, Vercel, Railway, etc.]
+```
+
+Every item must reference the actual config file or env var it was found in. No vague summaries.
+
+Write to Contextium:
+**CLI:** `cat << 'EOF' | contextium new <library-name> -t "Tech Stack" -p "stack.md" --stdin -w <workspace>`
+**MCP:** call mcp__contextium__create_file (or update_file if refreshing)
+
+Update the progress indicator to `✓ Tech stack & integrations`.
+</step>
+
+<step name="pass_2_architecture">
+**Architecture & Structure**
+
+Analyse and write `architecture.md` and `structure.md`:
+
+Get the full directory tree:
+```bash
+find . -type f -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" -not -path "*/.next/*" -not -path "*/build/*" | head -120
+```
+
+Find entry points:
+```bash
+ls src/index.* src/main.* src/app.* src/server.* app/page.* app/layout.* 2>/dev/null
+```
+
+Sample key files to understand patterns:
+```bash
+head -60 $(ls src/index.* src/main.* src/app.* 2>/dev/null | head -3) 2>/dev/null
+```
+
+Produce `architecture.md`:
+
+```markdown
+# Architecture
+**Analysis Date:** [today]
+
+## Pattern
+[MVC / layered / feature-based / monolith / microservices / etc — with evidence]
+
+## Layers
+[list each layer: what it contains, what it depends on, example files]
+
+## Data Flow
+[how a typical request flows through the system — entry point → handler → service → data layer]
+
+## Key Abstractions
+[important interfaces, base classes, shared utilities — with file paths]
+
+## Error Handling
+[how errors propagate — try/catch, result types, middleware, etc.]
+```
+
+Produce `structure.md`:
+
+```markdown
+# Structure
+**Analysis Date:** [today]
+
+## Directory Map
+[annotated directory tree showing purpose of each folder]
+
+## Key File Locations
+| Purpose | Path |
+|---------|------|
+| Entry point | `src/index.ts` |
+| Route definitions | `src/routes/` |
+| [etc] | [etc] |
+
+## Where to Add New Code
+[specific guidance: "New API routes go in src/routes/, follow the pattern in src/routes/users.ts"]
+
+## Naming Conventions
+[file naming, folder naming, component naming patterns with examples]
+```
+
+Write both files to Contextium. Update progress to `✓ Architecture & structure`.
+</step>
+
+<step name="pass_3_conventions">
+**Conventions & Testing**
+
+Analyse and write `conventions.md` and `testing.md`:
+
+Read linting/formatting config:
+```bash
+cat .eslintrc* eslint.config.* .prettierrc* biome.json 2>/dev/null
+```
+
+Sample source files to extract conventions:
+```bash
+head -80 $(find src/ app/ lib/ -name "*.ts" -o -name "*.tsx" -o -name "*.js" 2>/dev/null | grep -v test | grep -v spec | head -5) 2>/dev/null
+```
+
+Check testing setup:
+```bash
+cat jest.config.* vitest.config.* pytest.ini setup.cfg 2>/dev/null
+find . -name "*.test.*" -o -name "*.spec.*" 2>/dev/null | grep -v node_modules | head -20
+```
+
+Produce `conventions.md`:
+
+```markdown
+# Conventions
+**Analysis Date:** [today]
+
+## Naming
+[variables, functions, classes, files, folders — with real examples from the codebase]
+
+## Code Style
+[formatting rules, import order, export patterns — reference linting config]
+
+## Function Design
+[pure vs stateful, async patterns, error handling style]
+
+## State Management
+[how state is managed — context, stores, props — with example file paths]
+
+## Comments & Documentation
+[what gets documented and how]
+```
+
+Produce `testing.md`:
+
+```markdown
+# Testing
+**Analysis Date:** [today]
+
+## Framework & Setup
+[test runner, assertion library, config file location]
+
+## File Organisation
+[where tests live relative to source — colocated, __tests__, etc.]
+
+## Test Structure
+[describe/it patterns, setup/teardown conventions — with example from an existing test]
+
+## Mocking Approach
+[how dependencies are mocked — with example]
+
+## Coverage
+[what's covered, what's not, any coverage thresholds configured]
+
+## How to Run Tests
+[exact commands]
+```
+
+Write both files to Contextium. Update progress to `✓ Conventions & testing`.
+</step>
+
+<step name="pass_4_concerns">
+**Concerns & Tech Debt**
+
+Analyse and write `concerns.md`:
+
+Find tech debt markers:
+```bash
+grep -rn "TODO\|FIXME\|HACK\|XXX\|TEMP\|@deprecated" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" . 2>/dev/null | grep -v node_modules | head -60
+```
+
+Find large/complex files:
+```bash
+find . -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" 2>/dev/null | grep -v node_modules | grep -v dist | xargs wc -l 2>/dev/null | sort -rn | head -20
+```
+
+Find empty stubs or incomplete implementations:
+```bash
+grep -rn "throw new Error.*not implemented\|TODO.*implement\|return null\|pass$" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" . 2>/dev/null | grep -v node_modules | head -30
+```
+
+Check for hardcoded values that should be config:
+```bash
+grep -rn "localhost\|127\.0\.0\.1\|hardcoded\|magic number" --include="*.ts" --include="*.js" . 2>/dev/null | grep -v node_modules | grep -v test | head -20
+```
+
+Produce `concerns.md`:
+
+```markdown
+# Concerns & Tech Debt
+**Analysis Date:** [today]
+
+## Tech Debt
+| Issue | Location | Suggested Fix |
+|-------|----------|---------------|
+| [specific issue] | `src/path/file.ts:42` | [concrete fix approach] |
+
+## Known Gaps / Incomplete Features
+[stubs, TODOs marked as incomplete, features with placeholder implementations — file paths required]
+
+## Fragile Areas
+[files or patterns that are high-risk to modify — explain why and how to modify safely]
+
+## Security Observations
+[anything that looks like a security concern — never log secrets, only note patterns]
+
+## Test Coverage Gaps
+[areas with no tests that clearly need them]
+
+## Dependencies to Watch
+[outdated, deprecated, or high-risk dependencies found in package manifest]
+```
+
+Write to Contextium. Update progress to `✓ Concerns & tech debt`.
+</step>
+
+<step name="update_project_state">
+If a `project-state.md` file exists in any library in the loaded workflow, read it and check the `## Phases` section.
+
+For each phase whose described functionality clearly already exists in the codebase (based on what was found in the analysis), add a note under that phase:
+
+```
+> **Already built** — confirmed by codebase scan [date]
+```
+
+And update its status to "Complete" if the entire phase is done.
+
+If no `project-state.md` exists yet, skip this step silently.
+</step>
+
+<step name="summary">
+Show the final summary:
+
+```
+✓ Codebase scan complete
+
+Documents written to "<library name>":
+  ✓ stack.md          — tech stack, dependencies, integrations
+  ✓ architecture.md   — patterns, layers, data flow
+  ✓ structure.md      — directory map, where to add new code
+  ✓ conventions.md    — naming, code style, patterns
+  ✓ testing.md        — test framework, structure, coverage
+  ✓ concerns.md       — tech debt, gaps, fragile areas
+```
+
+Then ask:
+
+"Would you like to set up a new project plan now? Running /ium:new-project will use these documents to understand what's already built and only plan phases for what's missing."
+
+Use AskUserQuestion:
+- "Yes, run /ium:new-project now"
+- "No, I'll do it later"
+
+If yes: proceed with the /ium:new-project flow. The codebase analysis documents are now in the library and will be found automatically when the project state is being planned.
+</step>
+
+</process>
+
+<rules>
+- Never show raw bash output, file paths, or API responses to the user — only the progress indicators and final summary
+- Never read `.env` file contents — only check for the file's existence and read `.env.example` or `.env.sample`
+- Every finding in every document must reference a specific file path — no vague summaries
+- If a pass fails silently (no files found, permission error), write what was found and note "insufficient data to analyse [area]" — never skip the document entirely
+- Documents are written for future AI agents to consume, not as human prose — be specific, prescriptive, and grounded in actual file paths
+- When refreshing, always use update_file not create_file to preserve file history in Contextium
+- Only one set of codebase analysis documents should exist per library — never create duplicates
+</rules>