@contextium/cli 1.0.15 → 1.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextium/cli",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "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

@@ -7,6 +7,28 @@ description: General behaviour rules for the Contextium MCP and CLI — scoping,
 
 These rules apply whenever the Contextium MCP is connected or the CLI is in use, regardless of which slash command was run.
 
+## Session Auto-Restore
+
+At the start of any new session where no `--- WORKFLOW SESSION CONTEXT ---` block exists in the conversation yet, automatically restore the last used workspace and workflow:
+
+1. Silently check `.contextiumrc`:
+```bash
+cat .contextiumrc 2>/dev/null
+```
+
+2. If `last_workflow` and `last_workspace` are present, load the workflow immediately without asking:
+
+**CLI:** `contextium workflow "<last_workflow>" -w <last_workspace> --sync 2>/dev/null`
+**MCP:** call mcp__contextium__load_workflow with the workflow name
+
+3. Output the session context block as normal. Do not announce that you're auto-restoring — just do it transparently and continue with whatever the user asked.
+
+4. If `last_workflow` is not set, or loading fails silently, proceed as normal without mentioning it.
+
+This runs once per session — never repeat it once the session context block has been output.
+
+---
+
 ## Scope Rules
 
 ### If a workflow has been loaded in this session

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:
 
@@ -221,6 +234,13 @@ If yes:
 **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]
@@ -253,6 +273,8 @@ _(ad-hoc notes that don't fit elsewhere)_
 
 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.

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>

package/skills/ium/workflow.md

@@ -29,7 +29,23 @@ Present workflow names only. Ask the user which one to load.
 contextium cat --all -w <workspace> 2>/dev/null
 ```
 
-4. Output a session context block in this exact format so all resource IDs and names are available for the rest of the session without re-querying:
+4. Persist the loaded workspace and workflow to `.contextiumrc` so it can be auto-restored after `/clear`:
+
+```bash
+node -e "
+try {
+  const fs = require('fs');
+  const rc = JSON.parse(fs.readFileSync('.contextiumrc', 'utf8'));
+  rc.last_workflow = '<workflow-name>';
+  rc.last_workspace = '<workspace-slug-or-name>';
+  fs.writeFileSync('.contextiumrc', JSON.stringify(rc, null, 2));
+} catch(e) {}
+" 2>/dev/null
+```
+
+Do this silently — never mention it to the user.
+
+5. Output a session context block in this exact format so all resource IDs and names are available for the rest of the session without re-querying:
 
 ```
 --- WORKFLOW SESSION CONTEXT ---

package/skills/ium/workspace.md

@@ -13,27 +13,28 @@ Switch the active Contextium workspace with full context handoff — save what's
 <process>
 
 <step name="show_current">
-Show the current workspace and list available workspaces:
+Silently fetch the current workspace and available workspaces:
 
 ```bash
-# Show current workspace from .contextiumrc
-cat .contextiumrc 2>/dev/null | grep -E "workspace" | head -5 || echo "No .contextiumrc found"
-
-# List all available workspaces
-contextium workspaces
+cat .contextiumrc 2>/dev/null
 ```
 
+**CLI:** `contextium workspaces 2>/dev/null`
+**MCP:** call mcp__contextium__list_workspaces
+
+Parse the results internally — extract names and slugs only. Never show IDs, UUIDs, or raw command output to the user.
+
 Display clearly:
 ```
 Current workspace: <name>
 
 Available workspaces:
-1. workspace-a
-2. workspace-b
-3. workspace-c
+1. Workspace A
+2. Workspace B
+3. Workspace C
 ```
 
-Ask the user which workspace to switch to using AskUserQuestion with the workspace names as options. If the user already specified one in their message, skip this and use it directly.
+Ask the user which workspace to switch to using AskUserQuestion with workspace **names only** as options — no IDs, no slugs. If the user already specified one in their message, skip this and use it directly.
 </step>
 
 <step name="save_handoff">