@spekn/cli 1.0.1 → 1.0.2

package/dist/prompts/governance-analysis.prompt.md

@@ -0,0 +1,109 @@
+You are a governance analyst evaluating a repository's governance health. You have full access to the repository filesystem.
+
+## Repository Context:
+- Path: {{REPO_PATH}}{{LANG_CONTEXT}}{{SIZE_CONTEXT}}
+- **Static baseline score: {{STATIC_SCORE}}/100**
+- Per-check static scores:
+{{CHECK_SCORES}}
+
+## Governance Dimensions
+
+Evaluate the repository across these 6 governance dimensions. For each, read the relevant files and score independently.
+
+### 1. Agent Context Depth (`agent-context-depth`, maxScore: 143, weight: {{WEIGHT_AGENT_CONTEXT}})
+Evaluates how well the repo provides context to AI coding agents — regardless of which agent tools are used. Discover and read any agent context files present (common examples: AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md, GEMINI.md, or similar). Then evaluate the **quality of the context provided**, not which specific files exist:
+- Build/test/lint commands with runnable code blocks
+- Project structure / module map with annotated directories
+- Debugging / troubleshooting / known issues guidance
+- Current phase or focus indicator
+- Per-subsystem verification commands (not just one global test command)
+- Machine-parseable structure (headings, code blocks, YAML frontmatter)
+- Multi-directory coverage: does context mention all major source directories?
+- Modular context: is guidance split into focused files/sections, or one monolithic blob?
+- Nested/per-package context for monorepo subdirectories
+- Low content duplication across files (repeated sentences waste tokens)
+- Reasonable total size (avoid bloating agent context windows)
+
+Do NOT prescribe specific filenames, directory layouts, or tool-specific features. Evaluate what IS there and how useful it would be to any AI coding agent.
+
+### 2. Spec-Driven Traceability (`spec-traceability`, maxScore: 75, weight: {{WEIGHT_SPEC_TRACEABILITY}})
+Evaluates how well specifications drive development. Look for:
+- specs/ directory with markdown specification documents
+- Spec anchors (structured references like `auth.login.requirements`)
+- Code referencing spec anchors in comments
+- Spec generations (integer generation number in frontmatter)
+- Spec-to-code traceability links
+
+### 3. Governance Structure (`governance-structure`, maxScore: 70, weight: {{WEIGHT_GOVERNANCE_STRUCTURE}})
+Evaluates structural governance patterns. Look for:
+- .speknrc.json or equivalent config
+- CI/CD governance hooks (pre-commit, PR checks)
+- CODEOWNERS or equivalent ownership definitions
+- Contribution guidelines (CONTRIBUTING.md)
+- License file
+- Well-organized directory structure
+
+### 4. Decision Governance (`decision-governance`, maxScore: 60, weight: {{WEIGHT_DECISION_GOVERNANCE}})
+Evaluates architectural decision tracking. Look for:
+- decisions/ directory with decision records (ADRs/DRs)
+- Decision index file
+- Proper decision status tracking (proposed/accepted/deprecated)
+- Decision dating (createdAt, decidedAt timestamps)
+- Cross-references between decisions and specs
+- Decision templates
+
+### 5. Terminology Consistency (`terminology`, maxScore: 100, weight: {{WEIGHT_TERMINOLOGY}})
+Evaluates naming consistency across docs and code. Look for:
+- Consistent product name usage
+- No spelling/casing variants of key terms
+- Consistent component naming across docs and code
+- Code comments using correct terminology
+
+### 6. Specification Frontmatter Quality (`frontmatter-quality`, maxScore: 50, weight: {{WEIGHT_FRONTMATTER}})
+Evaluates the quality of YAML frontmatter in spec files. Look for:
+- Required fields: title, type
+- Optional: generation (positive integer)
+- Valid type values (intent, capability, architectural, workflow, operational, decision)
+- Valid status values (draft, review, active, archived)
+- Content hints (constraints, requirements, technical, guidance)
+- Relationships (dependsOn, extends, compatibleWith, conflictsWith)
+
+## Task
+
+1. Discover and read the repository's governance files — agent context files, specs/, decisions/, and any other governance artifacts
+2. Score each dimension independently (0 to maxScore)
+3. For each dimension, list specific findings with severity (error/warning/info) and actionable messages
+4. Provide strategic recommendations
+
+Respond ONLY with valid JSON (no markdown fences, no explanation outside JSON):
+{
+  "checkScores": [
+    {
+      "checkId": "string (one of the 6 IDs above)",
+      "score": "number (0 to maxScore for that check)",
+      "maxScore": "number (the maxScore listed above)",
+      "weight": "number (the weight listed above)",
+      "summary": "string (1-2 sentence assessment)",
+      "findings": [
+        {
+          "checkId": "string (same as parent)",
+          "severity": "error|warning|info",
+          "message": "string (specific, actionable finding)",
+          "file": "string (optional, relative file path)",
+          "autoFixable": false,
+          "speknCta": "string (optional, how Spekn helps)"
+        }
+      ]
+    }
+  ],
+  "rootCauses": "string (2-3 sentences: why do these governance gaps exist?)",
+  "priorities": [{"finding": "string", "reason": "string", "files": ["string"], "timeEstimate": "string", "scoreImpact": "string"}],
+  "quickWins": [{"action": "string", "steps": ["string"], "timeEstimate": "string", "scoreImpact": "string"}],
+  "architecturalRec": {"recommendation": "string", "implementation": ["string"], "scoreImpact": "string"},
+  "governanceImpact": {"currentScore": {{STATIC_SCORE}}, "potentialScore": "number (0-100 projected score after ALL recommended fixes)", "improvement": "number (potentialScore minus currentScore)"}
+}
+
+IMPORTANT:
+- governanceImpact.currentScore is FIXED at {{STATIC_SCORE}} (the actual static baseline). Do NOT recompute it.
+- governanceImpact.potentialScore should reflect your realistic estimate after all recommended fixes are applied. Must be 0-100.
+- Each check is normalized (score/maxScore) then weighted, so the headline score is a weighted average percentage, NOT a sum of raw scores.

package/dist/resources/prompts/repo-analysis.prompt.md

@@ -1,151 +1,43 @@
 You are analyzing a repository to register it with a Spekn project.
-You have been given Spekn MCP tools to create specifications and decisions.
+You have Spekn MCP tools available to create specifications and decisions.
 
 PROJECT ID: {{PROJECT_ID}}{{ORG_INSTRUCTION}}
 REPO PATH: {{REPO_PATH}}
 
-DISCOVERED FILES:
-{{FILE_LIST}}
-
-STEP 0 — VERIFY TOOLS:
-Before doing anything else, list the available MCP tools to confirm you have
-access to spekn_spec_create, spekn_spec_list, and spekn_decision_create. If these tools are NOT available,
-output "ERROR: Spekn MCP tools not available. Cannot proceed with analysis." and stop.
+DETECTED TECH STACK:
+{{TECH_STACK}}
 
-STEP 1 — READ AND UNDERSTAND THE REPOSITORY:
-Read the governance files (CLAUDE.md, AGENTS.md, README.md), package manifests
-(package.json, Cargo.toml, pyproject.toml, etc.), and key source directories
-to understand what this project does, its tech stack, and architecture.
-
-STEP 2 — CREATE MAIN PROJECT SPECIFICATION:
-Use spekn_spec_create to create a main project overview spec:
-  - Title: "Project Overview" — short, no repo name prefix
-  - Content MUST start with a YAML frontmatter block:
-    ---
-    title: "Project Overview"
-    type: intent
-    version: "1.0.0"
-    status: draft
-    author: "repo ingestor"
-    tags: [overview, project]
-    hints:
-      constraints: ["Key project invariants and boundaries"]
-      requirements: ["Core project goals and capabilities"]
-      technical: ["Tech stack, architecture patterns, build system"]
-      guidance: ["Development conventions and contribution guidelines"]
-    ---
-  - After the frontmatter, include a comprehensive explanation of what the project does,
-    tech stack, directory structure, build system, development conventions, and key decisions
-  - This becomes the primary context for the engineering manager agent
+DISCOVERED DOCUMENTATION FILES:
+{{FILE_LIST}}
 
-STEP 3 — IMPORT EXISTING SPECS:
-For each file categorized as "spec" in the DISCOVERED FILES list:
-  - Read the file content
-  - Use spekn_spec_create to create a Specification record
-  - Use the first # heading as the title (must be unique, 3-100 chars)
-  - If the file already has a YAML frontmatter block (---), preserve it but ensure author is set:
-    - author: "repo ingestor" (add it when missing)
-  - If no frontmatter exists, prepend one with:
-    - type: "capability"
-    - version: "1.0.0"
-    - author: "repo ingestor"
-    - hints: populate from the file content (constraints, requirements, technical, guidance)
-  - Set version to "1.0.0"
+NOTE: The list above contains only governance, spec, decision, and documentation files.
+You MUST explore source code directories yourself using your filesystem tools (ls, Glob, Read).
+The source code is your PRIMARY input for understanding the project and creating domain specs.
 
-For each file categorized as "decision" in the DISCOVERED FILES list:
-  - Read the file content
-  - First create/import its parent specification with spekn_spec_create if needed (type: "decision", author: "repo ingestor")
-  - Then perform ACP DECISION DETECTION before creating records:
-    - Extract one normalized decision object per explicit decision/ADR entry
-    - Ignore vague notes that do not state a concrete choice
-    - If one file contains multiple explicit ADR entries, create one decision record per entry
-  - Use this normalized structure for each extracted decision:
-    {
-      "title": "<3-100 chars, imperative/statement form>",
-      "description": "<what was decided, specific and concrete>",
-      "rationale": "<why this option was chosen>",
-      "alternatives": ["<rejected option 1>", "<rejected option 2>"]
-    }
-  - Formatting requirements:
-    - title must NOT include prefixes like "Decision:", "ADR-001:", markdown symbols, or file names
-    - description and rationale must be plain text (no markdown headings/bullets)
-    - alternatives must be plain option strings; use [] when none are explicit
-    - If rationale is missing, infer a concise rationale from nearby context (trade-offs/constraints)
-  - Create each record with spekn_decision_create using:
-    - projectId: PROJECT ID
-    - specificationId: parent decision specification ID
-    - title, description, rationale, alternatives from normalized object
+────────────────────────────────────────────────────────────────────────
+INSTRUCTIONS
+────────────────────────────────────────────────────────────────────────
 
-STEP 4 — ANALYZE PDF DOCUMENTS:
-If any files categorized as "pdf" appear in the DISCOVERED FILES list:
-  - Check whether you have a tool that can read or extract text from PDF files
-    (e.g. `read_file` with PDF support, a `pdf` skill, or any PDF extraction tool)
-  - If you DO have PDF capability:
-    - Read each PDF file to extract its text content
-    - Determine what the document covers (architecture diagrams, requirements, RFCs,
-      compliance docs, contracts, design documents, etc.)
-    - For each PDF that contains specification-worthy content, use spekn_spec_create:
-      - Title: short descriptive name derived from the PDF content (NOT the filename)
-      - Content MUST start with a YAML frontmatter block:
-        - type: choose the best fit ("capability", "architectural", "intent", "operational")
-        - status: "draft"
-        - author: "repo ingestor"
-        - tags: ["pdf-import", ...relevant tags]
-        - hints: summarize key content in each layer
-      - After frontmatter, include the extracted content reformatted as clean markdown
-    - For PDFs containing decision records or ADRs, create decisions following STEP 3 rules
-  - If you do NOT have PDF capability:
-    - Log: "PDF files found but no PDF reading tool available — skipping PDF analysis"
-    - List the PDF files that were skipped so the user knows
-  - Do NOT fail the entire analysis if PDF reading is unavailable
+Before starting work, load the Spekn specification format and workflow
+instructions from the MCP server. Load each of these prompts in order:
 
-STEP 5 — ASSESS GOVERNANCE AND CREATE IMPROVEMENT SPECS:
-Assess governance quality — does the repo have CI/CD, tests, security guidelines,
-contribution guidelines, documentation structure?
-For each significant gap, use spekn_spec_create to create a draft improvement spec:
-  - Descriptive title (e.g. "CI/CD Pipeline", "Testing Strategy")
-  - Content MUST start with a YAML frontmatter block:
-    - type: "capability" for new features, "operational" for ops/process improvements
-    - status: "draft"
-    - author: "repo ingestor"
-    - tags: reflecting the gap area (e.g., [ci-cd, automation] or [testing, quality])
-    - hints: summarize what the spec covers in each context layer
-  - After frontmatter, describe what the repo SHOULD have (best practices)
-  - Focus on quality over quantity — only create specs for real gaps
+1. spekn-spec-format — full specification format reference (frontmatter, body, YAML rules)
+2. spekn-anchor-format — anchor heading rules and per-anchor required fields
+3. spekn-quality-scoring — self-scoring checklist and quality rules
+4. spekn-repo-analysis (with args: { "projectId": "{{PROJECT_ID}}" }) — 6-step repo analysis workflow
 
-STEP 6 — FEATURE COVERAGE AND PLAN GAP ANALYSIS:
-Analyze feature implementation coverage against specs/FEATURE_MAP.md and related feature docs.
-- Read specs/FEATURE_MAP.md and list all rows marked "Planned", "Draft", "Active", "~95%", "pending", or "deferred"
-- For each such row, verify whether the repo has:
-  - implementation evidence in code (routers/services/components/tests)
-  - a corresponding feature document in specs/features/
-  - an implementation plan (IMPLEMENTATION_PLAN.md) when feature status implies planning/active build
-- For missing or weakly-covered items, create improvement specs with spekn_spec_create:
-  - Title: short descriptive name of the feature gap (e.g. "Flatpak Governance Enforcement", "Network Egress Policy")
-  - Do NOT prefix titles with the repo name, "Gap:", or any other prefix
-  - type: "capability" for product/runtime gaps, "operational" for process/governance gaps
-  - tags must include "feature-coverage" and "plan-gap"
-  - hints must explicitly include missing code surfaces and missing planning artifacts
-- Do not duplicate if an equivalent gap spec already exists; update existing draft instead when possible
+HOW TO LOAD PROMPTS (try in order):
+  A) Use the MCP prompts protocol: prompts/get with name "spekn-spec-format", etc.
+  B) If prompts are not available, call the tool: spekn_prompt_get(name: "spekn-spec-format"), etc.
+  C) If both fail, report the failure and continue — do NOT stop the workflow entirely.
 
-STEP 7 — SUMMARY:
-Print a summary of what you created:
-  - Number of specs imported from existing files
-  - Number of specs imported from PDF documents (or skipped if no PDF tool)
-  - Number of decisions created from decision files
-  - Number of improvement specs created
-  - Overall governance assessment (strengths and gaps)
-  - Feature coverage summary (implemented vs partial vs missing)
-  - Missing plan features summary
-  - Include a "FEATURE_COVERAGE" section in this exact line format:
-    - FEATURE | <id-or-name> | <status> | <evidence-or-missing>
-  - Include a "MISSING_PLAN_FEATURES" section in this exact line format:
-    - PLAN_GAP | <id-or-name> | <missing-artifact> | <recommended-spec-title>
-  - Include a "DECISIONS_CREATED" section in this exact line format:
-    - DECISION | <source-file> | <title> | <specificationId>
+Read and internalize each prompt's content, then follow the workflow
+steps from spekn-repo-analysis using the runtime context above (tech
+stack, discovered files, repo path) as your input data.
 
 RULES:
-- ALWAYS use Spekn MCP create tools (spekn_spec_create / spekn_decision_create) — never just describe what you would create
-- Each spec title must be unique within the project — use short descriptive titles, never prefix with repo name
-- Do NOT create specs for governance files (CLAUDE.md, AGENTS.md, .cursorrules) — those are context, not specs
+- ALWAYS use MCP tools (spekn_spec_create / spekn_decision_create) — never just describe what you would create
+- Every spec MUST follow the format from spekn-spec-format
+- Every spec MUST score at least B (75+) per the spekn-quality-scoring checklist
 - If a tool call fails, report the error and continue with the next item
+- Do NOT create specs for governance files (CLAUDE.md, AGENTS.md, .cursorrules)

package/dist/resources/prompts/repo-sync-analysis.prompt.md

@@ -3,83 +3,46 @@ Your role is to detect drift, decide what to update, and avoid duplicate specs.
 
 PROJECT ID: {{PROJECT_ID}}{{ORG_INSTRUCTION}}
 REPO PATH: {{REPO_PATH}}
+
 COMMIT CONTEXT:
 {{COMMIT_CONTEXT}}
 
-DISCOVERED FILES:
-{{FILE_LIST}}
-
-STEP 0 — VERIFY TOOLS:
-List available tools and confirm you have:
-- spekn_spec_list
-- spekn_spec_create
-- spekn_spec_update
-- spekn_decision_create
-- spekn_decision_update
-If missing critical tools, output an error and stop.
+DETECTED TECH STACK:
+{{TECH_STACK}}
 
-STEP 1 — LOAD CURRENT SaaS STATE FIRST:
-Before touching anything:
-1. Call spekn_spec_list for the project using pagination.
-   - API limit is max 100 items per page.
-   - Use `limit <= 100` and increment `offset` until no more items are returned.
-2. Build a map of existing specs by:
-   - exact title
-   - normalized title (case/spacing/punctuation insensitive)
-3. Treat locked specs as canonical. Never create a duplicate just because content differs.
+DISCOVERED DOCUMENTATION FILES:
+{{FILE_LIST}}
 
-STEP 2 — FILTER NON-SOURCE EXPORT ARTIFACTS:
-Files under `spekn/context/specs/**` and `spekn/context/decisions/**` are export artifacts.
-Do NOT re-import these as new specs by default.
-Only use them as evidence for drift, not as direct create input.
+NOTE: The list above contains only governance, spec, decision, and documentation files.
+You have full filesystem access — use ls, Glob, and Read to explore source code directories
+when you need to understand code changes, detect new modules, or verify drift.
 
-STEP 3 — FOR EACH DISCOVERED SOURCE FILE, DECIDE ACTION:
-For each relevant source file, choose exactly one:
-- SKIP: no meaningful drift
-- UPDATE_EXISTING: matching spec exists and should be updated
-- CREATE_NEW: truly new capability/intent/decision area with no equivalent existing spec
+────────────────────────────────────────────────────────────────────────
+INSTRUCTIONS
+────────────────────────────────────────────────────────────────────────
 
-Decision policy:
-- Prefer UPDATE_EXISTING over CREATE_NEW when a semantically equivalent spec exists.
-- CREATE_NEW only when no reasonable existing target exists.
-- Never create a “repo ingestor import ...” duplicate of an existing locked/canonical spec.
-- If uncertain between update and create, choose update and explain rationale.
-- Give extra weight to commit-range changes since LAST_SYNC_COMMIT when deciding drift.
-- If code/protocol files changed, verify corresponding specs/decisions were updated; if not, propose targeted updates.
+Before starting work, load the Spekn specification format and workflow
+instructions from the MCP server. Load each of these prompts in order:
 
-STEP 4 — APPLY CHANGES:
-- Use spekn_spec_update for UPDATE_EXISTING actions.
-- Use spekn_spec_create only for CREATE_NEW actions.
-- Use decision create/update tools similarly with dedupe intent.
-- Keep titles stable for existing specs; avoid generating near-duplicate titles.
-- For UPDATE_EXISTING calls, include version/history intent:
-  - prefer `changeType: "patch"` for small clarifications
-  - use `changeType: "minor"` for new requirements/constraints
-  - set concise `changeDescription` referencing commit-range drift rationale
+1. spekn-spec-format — full specification format reference (frontmatter, body, YAML rules)
+2. spekn-anchor-format — anchor heading rules and per-anchor required fields
+3. spekn-quality-scoring — self-scoring checklist and quality rules
+4. spekn-repo-sync (with args: { "projectId": "{{PROJECT_ID}}" }) — 5-step repo sync workflow
 
-STEP 4.5 — ASK FOR APPROVAL WHEN CONFIDENCE IS LOW:
-Before applying a low-confidence update/create (for example: weak evidence, ambiguous target mapping, or conflicting interpretation):
-- trigger an interactive ACP question to the client (`session/prompt`) with explicit options:
-  - approve
-  - skip
-- if approval is not explicit, skip the low-confidence change
-- mention each prompted item again in REVIEW_NOTES
+HOW TO LOAD PROMPTS (try in order):
+  A) Use the MCP prompts protocol: prompts/get with name "spekn-spec-format", etc.
+  B) If prompts are not available, call the tool: spekn_prompt_get(name: "spekn-spec-format"), etc.
+  C) If both fail, report the failure and continue — do NOT stop the workflow entirely.
 
-STEP 5 — OUTPUT SUMMARY:
-Output:
-1. DRIFT_SUMMARY
-   - file, drift type, severity, target spec (if any)
-2. SYNC_ACTION_PLAN
-   - ACTION | SKIP/UPDATE_EXISTING/CREATE_NEW | file | target/new title | reason
-3. SYNC_APPLIED
-   - APPLIED | update/create/skip | entity type | id/title
-4. REVIEW_NOTES
-   - low-confidence updates that should be human-reviewed
-   - missing spec/decision coverage for changed code/protocol files
+Read and internalize each prompt's content, then follow the workflow
+steps from spekn-repo-sync using the runtime context above (tech stack,
+discovered files, repo path, commit context) as your input data.
 
 RULES:
-- Do not mass-create specs.
-- Minimize churn.
-- Respect existing canonical spec set.
-- Every tool call must include projectId and organizationId when required.
-- Spec titles must be short and descriptive — never prefix with the repo name, "Gap:", or other prefixes.
+- ALWAYS use MCP tools (spekn_spec_create / spekn_spec_update / spekn_decision_create) — never just describe what you would create
+- Every spec MUST follow the format from spekn-spec-format
+- Every spec MUST score at least B (75+) per the spekn-quality-scoring checklist
+- Frontmatter MUST stay under 2048 bytes — if a tool call fails with size limit, trim and retry
+- Minimize churn — prefer updates over new specs
+- Respect existing canonical spec set
+- If a tool call fails for other reasons, report the error and continue with the next item

package/dist/tui/app.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+import type { TuiScreenId } from './types';
+export declare function TuiApp({ apiUrl, initialScreen, projectId }: {
+    apiUrl: string;
+    initialScreen: TuiScreenId;
+    projectId?: string;
+}): React.JSX.Element;

package/dist/tui/app.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TuiApp = TuiApp;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const ink_1 = require("ink");
+const ui_1 = require("@inkjs/ui");
+const use_app_state_1 = require("./state/use-app-state");
+const use_global_keymap_1 = require("./keymap/use-global-keymap");
+const frame_1 = require("./components/frame");
+const status_bar_1 = require("./components/status-bar");
+const home_1 = require("./screens/home");
+const specs_1 = require("./screens/specs");
+const export_1 = require("./screens/export");
+const decisions_1 = require("./screens/decisions");
+const bridge_1 = require("./screens/bridge");
+const locked_1 = require("./screens/locked");
+/** Brand-aligned theme: Electric Indigo spinner, semantic colors via component defaults */
+const speknTheme = (0, ui_1.extendTheme)(ui_1.defaultTheme, {
+    components: {
+        Spinner: {
+            styles: {
+                frame: () => ({ color: '#6366F1' }),
+            },
+        },
+    },
+});
+function renderMainScreen(screen, state) {
+    if (screen === 'home')
+        return (0, jsx_runtime_1.jsx)(home_1.HomeScreen, { state: state });
+    if (screen === 'specs')
+        return (0, jsx_runtime_1.jsx)(specs_1.SpecsScreen, { state: state });
+    if (screen === 'export')
+        return (0, jsx_runtime_1.jsx)(export_1.ExportScreen, { state: state });
+    if (screen === 'decisions')
+        return (0, jsx_runtime_1.jsx)(decisions_1.DecisionsScreen, { state: state });
+    if (screen === 'bridge')
+        return (0, jsx_runtime_1.jsx)(bridge_1.BridgeScreen, { state: state });
+    const nav = state.navPolicy.find((item) => item.id === screen);
+    return (0, jsx_runtime_1.jsx)(locked_1.LockedScreen, { item: nav });
+}
+function TuiApp({ apiUrl, initialScreen, projectId }) {
+    const { state, refresh, setScreen, toggleHelp, setSearchQuery, setCommandMode, setExportFormat, previewExport, generateExport, bridgeStart, bridgeStop, appendLog, } = (0, use_app_state_1.useAppState)(apiUrl, initialScreen, projectId);
+    (0, use_global_keymap_1.useGlobalKeymap)({
+        screen: state.screen,
+        navPolicy: state.navPolicy,
+        commandMode: state.commandMode,
+        showHelp: state.showHelp,
+        onNavigate: setScreen,
+        onHelpToggle: toggleHelp,
+        onSearchToggle: () => setSearchQuery(state.searchQuery ? '' : '*'),
+        onSearchClear: () => setSearchQuery(''),
+        onCommandModeToggle: setCommandMode,
+        onRefresh: () => {
+            void refresh();
+        },
+        onExportPreview: () => {
+            void previewExport();
+        },
+        onExportGenerate: () => {
+            void generateExport();
+        },
+        onBridgeStart: bridgeStart,
+        onBridgeStop: () => {
+            void bridgeStop();
+        },
+    });
+    const handleCommandSubmit = (command) => {
+        const normalized = command.trim().toLowerCase();
+        setCommandMode(false);
+        if (!normalized)
+            return;
+        if (normalized === 'help') {
+            toggleHelp();
+            return;
+        }
+        if (normalized === 'refresh' || normalized === 'r') {
+            void refresh();
+            return;
+        }
+        if (normalized.startsWith('goto ')) {
+            const target = normalized.replace('goto ', '').trim();
+            setScreen(target);
+            appendLog(`[nav] goto ${target}`);
+            return;
+        }
+        if (normalized === 'show specs') {
+            setScreen('specs');
+            return;
+        }
+        if (normalized === 'show export') {
+            setScreen('export');
+            return;
+        }
+        if (normalized === 'run export') {
+            void generateExport();
+            return;
+        }
+        if (normalized === 'format claude') {
+            setExportFormat('claude-md');
+            appendLog('[export] Format switched to claude-md');
+            return;
+        }
+        if (normalized === 'format cursor') {
+            setExportFormat('cursorrules');
+            appendLog('[export] Format switched to cursorrules');
+            return;
+        }
+        if (normalized === 'bridge start') {
+            bridgeStart();
+            return;
+        }
+        if (normalized === 'bridge stop') {
+            void bridgeStop();
+            return;
+        }
+        appendLog(`[command] Unknown: ${command}`);
+    };
+    const left = `${state.boot?.organizationName ?? '...'} / ${state.boot?.projectName ?? '...'}`;
+    const center = state.loading ? 'Loading...' : state.statusLine;
+    const right = `${state.screen} | phase:${state.workflow.currentPhase ?? 'n/a'} | role:${state.boot?.role ?? 'n/a'} | tier:${state.boot?.plan ?? 'n/a'}`;
+    return ((0, jsx_runtime_1.jsx)(ui_1.ThemeProvider, { theme: speknTheme, children: (0, jsx_runtime_1.jsxs)(ink_1.Box, { flexDirection: "column", children: [(0, jsx_runtime_1.jsx)(ink_1.Text, { bold: true, color: "cyan", children: "Spekn TUI - Technical Cockpit" }), (0, jsx_runtime_1.jsx)(ink_1.Text, { color: "gray", children: "Shortcuts: j/k/h/l nav, : commands, ? help, r refresh, Ctrl+C quit" }), state.error ? ((0, jsx_runtime_1.jsx)(ink_1.Box, { marginTop: 1, children: (0, jsx_runtime_1.jsx)(ui_1.Alert, { variant: "error", children: state.error }) })) : null, (0, jsx_runtime_1.jsxs)(ink_1.Box, { marginTop: 1, children: [(0, jsx_runtime_1.jsx)(ink_1.Box, { width: "28%", flexDirection: "column", children: (0, jsx_runtime_1.jsx)(frame_1.Frame, { title: "Navigation", children: state.navPolicy.map((item, index) => ((0, jsx_runtime_1.jsxs)(ink_1.Text, { color: state.screen === item.id ? 'green' : item.state === 'locked' ? 'yellow' : item.state === 'disabled' ? 'gray' : undefined, children: [state.screen === item.id ? '>' : ' ', " ", index + 1, ". ", item.label, item.state === 'locked' ? ' (locked)' : item.state === 'disabled' ? ' (disabled)' : ''] }, item.id))) }) }), (0, jsx_runtime_1.jsx)(ink_1.Box, { width: "52%", flexDirection: "column", children: (0, jsx_runtime_1.jsx)(frame_1.Frame, { title: "Context", children: renderMainScreen(state.screen, state) }) }), (0, jsx_runtime_1.jsx)(ink_1.Box, { width: "20%", flexDirection: "column", children: (0, jsx_runtime_1.jsx)(frame_1.Frame, { title: "Event Log", dim: true, children: (state.logs.length === 0 ? ['[system] ready'] : state.logs.slice(0, 7)).map((line, index) => ((0, jsx_runtime_1.jsx)(ink_1.Text, { color: "gray", children: line }, `log-${index}`))) }) })] }), state.showHelp ? ((0, jsx_runtime_1.jsx)(ink_1.Box, { marginTop: 1, children: (0, jsx_runtime_1.jsx)(ui_1.Alert, { variant: "info", children: "Help: j/k/h/l navigate | :help | :goto specs | :run export | format claude/cursor | bridge start/stop" }) })) : null, state.commandMode ? ((0, jsx_runtime_1.jsxs)(ink_1.Box, { marginTop: 1, children: [(0, jsx_runtime_1.jsx)(ink_1.Text, { color: "green", children: ":" }), (0, jsx_runtime_1.jsx)(ui_1.TextInput, { placeholder: "command...", onSubmit: handleCommandSubmit })] })) : null, (0, jsx_runtime_1.jsx)(status_bar_1.StatusBar, { left: left, center: center, right: right })] }) }));
+}

package/dist/tui/args.d.ts

@@ -0,0 +1,8 @@
+import type { TuiScreenId } from './types';
+export interface TuiCliOptions {
+    projectId?: string;
+    apiUrl: string;
+    initialView: TuiScreenId;
+    noColor: boolean;
+}
+export declare function parseTuiArgs(args: string[]): TuiCliOptions;

package/dist/tui/args.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTuiArgs = parseTuiArgs;
+const VIEW_ALIASES = {
+    home: 'home',
+    specs: 'specs',
+    export: 'export',
+    decisions: 'decisions',
+    bridge: 'bridge',
+};
+function parseTuiArgs(args) {
+    let projectId;
+    let apiUrl = process.env.SPEKN_API_URL ?? 'http://localhost:3000';
+    let initialView = 'home';
+    let noColor = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if ((arg === '--project-id' || arg === '--project') && args[i + 1]) {
+            projectId = args[++i];
+            continue;
+        }
+        if (arg.startsWith('--project-id=')) {
+            projectId = arg.slice('--project-id='.length);
+            continue;
+        }
+        if (arg === '--api-url' && args[i + 1]) {
+            apiUrl = args[++i];
+            continue;
+        }
+        if (arg.startsWith('--api-url=')) {
+            apiUrl = arg.slice('--api-url='.length);
+            continue;
+        }
+        if (arg === '--view' && args[i + 1]) {
+            const candidate = VIEW_ALIASES[String(args[++i]).toLowerCase()];
+            if (candidate)
+                initialView = candidate;
+            continue;
+        }
+        if (arg.startsWith('--view=')) {
+            const candidate = VIEW_ALIASES[arg.slice('--view='.length).toLowerCase()];
+            if (candidate)
+                initialView = candidate;
+            continue;
+        }
+        if (arg === '--no-color') {
+            noColor = true;
+            continue;
+        }
+    }
+    return {
+        projectId,
+        apiUrl,
+        initialView,
+        noColor,
+    };
+}

package/dist/tui/capabilities/policy.d.ts

@@ -0,0 +1,7 @@
+import { OrganizationPlan } from '../shared-enums';
+import type { CapabilityContext, NavItemPolicy } from '../types';
+type OrganizationPlanType = (typeof OrganizationPlan)[keyof typeof OrganizationPlan];
+export declare function meetsMinimumTier(current: OrganizationPlanType, required: OrganizationPlanType): boolean;
+export declare function resolveNavPolicy(ctx: CapabilityContext): NavItemPolicy[];
+export declare function isActionAllowed(policy: NavItemPolicy): boolean;
+export {};