@lsctech/polaris 0.3.22 → 0.3.24

package/dist/cli/adopt-assets.js

@@ -155,6 +155,19 @@ function installWorkspaceAssets(repoRoot, workspaceDir) {
         const smartdocsPreExisted = (0, node_fs_1.existsSync)(dstSmartdocs);
         installSmartdocsDir(srcSmartdocs, dstSmartdocs, "smartdocs", installed, alreadyPresent, smartdocsPreExisted);
     }
+    // 5. POLARIS_RULES.md template
+    const rulesRel = "POLARIS_RULES.md";
+    const srcRules = (0, node_path_1.join)(workspaceDir, rulesRel);
+    const dstRules = (0, node_path_1.join)(repoRoot, rulesRel);
+    if ((0, node_fs_1.existsSync)(srcRules)) {
+        if ((0, node_fs_1.existsSync)(dstRules)) {
+            alreadyPresent.push(rulesRel);
+        }
+        else {
+            (0, node_fs_1.copyFileSync)(srcRules, dstRules);
+            installed.push(rulesRel);
+        }
+    }
     return { installed, alreadyPresent, skipped, conflicted };
 }
 function runGraphBuild(repoRoot) {

package/dist/cli/adopt-genesis.js

@@ -9,16 +9,69 @@ const AGENT_FILES = ["CLAUDE.md", "AGENTS.md", ".github/copilot-instructions.md"
 function formatDate(d) {
     return d.toISOString().slice(0, 10);
 }
+function isAlreadyPointer(content) {
+    // isThinPointer checks for POLARIS.md; also accept POLARIS_RULES.md references
+    if ((0, adopt_assets_js_1.isThinPointer)(content))
+        return true;
+    // Check for POLARIS_RULES.md thin pointer (≤3 meaningful lines + POLARIS_RULES.md reference)
+    const lines = content.split("\n");
+    const meaningfulLines = lines.filter((line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return false;
+        if (/^<!--.*-->$/.test(trimmed))
+            return false;
+        return true;
+    });
+    return meaningfulLines.length <= 3 && meaningfulLines.some((line) => line.includes("POLARIS_RULES.md"));
+}
+function appendGenesisProvenance(repoRoot, records) {
+    if (records.length === 0)
+        return;
+    const provenancePath = (0, node_path_1.join)(repoRoot, ".polaris", "adoption-provenance.json");
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, ".polaris"), { recursive: true });
+    let existing = {};
+    if ((0, node_fs_1.existsSync)(provenancePath)) {
+        try {
+            const parsed = JSON.parse((0, node_fs_1.readFileSync)(provenancePath, "utf-8"));
+            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+                existing = parsed;
+            }
+        }
+        catch {
+            existing = {};
+        }
+    }
+    const prior = Array.isArray(existing.genesis_reconcile_actions)
+        ? existing.genesis_reconcile_actions
+        : [];
+    const updated = {
+        ...existing,
+        updated_at: new Date().toISOString(),
+        genesis_reconcile_actions: [...prior, ...records],
+    };
+    (0, node_fs_1.writeFileSync)(provenancePath, `${JSON.stringify(updated, null, 2)}\n`, "utf-8");
+}
 async function reconcileAgentFiles(repoRoot, options) {
     const results = [];
+    const provenanceRecords = [];
+    const now = options?.now ?? new Date();
+    const timestamp = now.toISOString();
     for (const file of AGENT_FILES) {
         const filePath = (0, node_path_1.join)(repoRoot, file);
         if (!(0, node_fs_1.existsSync)(filePath)) {
             continue;
         }
         const content = (0, node_fs_1.readFileSync)(filePath, "utf8");
-        if ((0, adopt_assets_js_1.isThinPointer)(content)) {
+        if (isAlreadyPointer(content)) {
             results.push({ file, outcome: "already-present" });
+            provenanceRecords.push({
+                source_path: file,
+                backup_path: null,
+                decision: "already-pointer",
+                timestamp,
+                migration_outcome: "already-present",
+            });
             continue;
         }
         const rl = (0, promises_1.createInterface)({ input: process.stdin, output: process.stdout });
@@ -31,9 +84,16 @@ async function reconcileAgentFiles(repoRoot, options) {
         }
         const trimmed = answer.trim().toLowerCase();
         if (trimmed === "n" || trimmed === "no") {
-            const pointer = `<!-- See [POLARIS.md](POLARIS.md) for repo instructions -->\n`;
+            const pointer = `<!-- See [POLARIS_RULES.md](POLARIS_RULES.md) for repo instructions -->\n`;
             (0, node_fs_1.writeFileSync)(filePath, pointer + content, "utf8");
             results.push({ file, outcome: "refused" });
+            provenanceRecords.push({
+                source_path: file,
+                backup_path: null,
+                decision: "refused-compression",
+                timestamp,
+                migration_outcome: "refused",
+            });
             continue;
         }
         // Accepted — attempt compression
@@ -41,6 +101,13 @@ async function reconcileAgentFiles(repoRoot, options) {
         if (!apiKey) {
             process.stderr.write(`Warning: ANTHROPIC_API_KEY not found. Skipping compression of ${file}.\n`);
             results.push({ file, outcome: "skipped" });
+            provenanceRecords.push({
+                source_path: file,
+                backup_path: null,
+                decision: "skipped-no-api-key",
+                timestamp,
+                migration_outcome: "skipped",
+            });
             continue;
         }
         let Anthropic;
@@ -52,6 +119,13 @@ async function reconcileAgentFiles(repoRoot, options) {
         catch {
             process.stderr.write(`Warning: @anthropic-ai/sdk not installed. Skipping compression of ${file}.\n`);
             results.push({ file, outcome: "skipped" });
+            provenanceRecords.push({
+                source_path: file,
+                backup_path: null,
+                decision: "skipped-no-sdk",
+                timestamp,
+                migration_outcome: "skipped",
+            });
             continue;
         }
         const client = new Anthropic({ apiKey });
@@ -69,16 +143,23 @@ async function reconcileAgentFiles(repoRoot, options) {
             .filter((b) => b.type === "text")
             .map((b) => b.text)
             .join("\n");
-        const now = options?.now ?? new Date();
         const dateStr = formatDate(now);
         const genesisPath = `smartdocs/doctrine/active/${dateStr}-genesis-agent-doctrine.md`;
         const genesisFullPath = (0, node_path_1.join)(repoRoot, genesisPath);
         (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, "smartdocs/doctrine/active"), { recursive: true });
         (0, node_fs_1.writeFileSync)(genesisFullPath, distilled, "utf8");
-        const thinPointer = `# Agent Instructions\n\nRead [POLARIS.md](POLARIS.md) before beginning any work.\n\n` +
+        const thinPointer = `# Agent Instructions\n\nRead [POLARIS_RULES.md](POLARIS_RULES.md) before beginning any work.\n\n` +
             `<!-- genesis doctrine archived: ${genesisPath} -->\n`;
         (0, node_fs_1.writeFileSync)(filePath, thinPointer, "utf8");
         results.push({ file, outcome: "compressed", genesisPath });
+        provenanceRecords.push({
+            source_path: file,
+            backup_path: genesisPath,
+            decision: "accepted-compression",
+            timestamp,
+            migration_outcome: "compressed",
+        });
     }
+    appendGenesisProvenance(repoRoot, provenanceRecords);
     return results;
 }

package/dist/cli/adopt-instructions.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleInstructionFiles = handleInstructionFiles;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const DELEGATION_MARKERS = ["<!-- polaris:delegate", "POLARIS.md", "Polaris runtime"];
+const DELEGATION_MARKERS = ["<!-- polaris:delegate", "POLARIS_RULES.md", "POLARIS.md", "Polaris runtime"];
 function isSupportedInstructionPath(path) {
     return (path === "CLAUDE.md" ||
         path === "AGENTS.md" ||
@@ -102,7 +102,7 @@ function appendInstructionProvenance(repoRoot, records) {
 }
 function handleInstructionFiles(plan, inventory, repoRoot) {
     if (plan.dry_run) {
-        return Promise.resolve();
+        return Promise.resolve([]);
     }
     const doctrineExists = hasDoctrine(repoRoot);
     const now = new Date().toISOString();
@@ -138,5 +138,5 @@ function handleInstructionFiles(plan, inventory, repoRoot) {
         });
     }
     appendInstructionProvenance(repoRoot, provenance);
-    return Promise.resolve();
+    return Promise.resolve(provenance);
 }

package/dist/cli/adopt-report.js

@@ -6,7 +6,7 @@ exports.printAdoptionReport = printAdoptionReport;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 function buildAdoptionReport(options) {
-    const { install, graph, agents, now } = options;
+    const { install, graph, agents, instructionMigration, now } = options;
     const timestamp = (now ?? new Date()).toISOString();
     return {
         timestamp,
@@ -18,6 +18,7 @@ function buildAdoptionReport(options) {
         graphDetail: graph.stdout ?? graph.reason,
         graphFollowUp: graph.followUpCommand,
         agents,
+        instructionMigration: instructionMigration ?? [],
     };
 }
 function writeAdoptionReport(repoRoot, report) {
@@ -56,6 +57,19 @@ function printAdoptionReport(report) {
         }
     }
     console.log("");
+    console.log("Instruction Migration:");
+    if (report.instructionMigration.length === 0) {
+        console.log("  (none)");
+    }
+    else {
+        for (const record of report.instructionMigration) {
+            console.log(`  ${record.source_path}: ${record.decision}`);
+            if (record.backup_path) {
+                console.log(`    -> archived to ${record.backup_path}`);
+            }
+        }
+    }
+    console.log("");
     console.log("Graph Build:");
     console.log(`  Status: ${report.graphStatus}`);
     if (report.graphDetail) {

package/dist/cli/adopt-rules.js

@@ -15,14 +15,12 @@ function buildRepoOverview(inventory) {
     }
     return lines.join(" ").trim() || "Repository managed by Polaris.";
 }
-async function generatePolarisRules(repoRoot, inventory, options = {}) {
-    const { overwrite = true } = options;
-    const outputPath = (0, node_path_1.join)(repoRoot, "POLARIS_RULES.md");
-    if ((0, node_fs_1.existsSync)(outputPath) && !overwrite) {
-        return;
-    }
-    const overview = buildRepoOverview(inventory);
-    const content = [
+function buildContentFromTemplate(templatePath, overview) {
+    const template = (0, node_fs_1.readFileSync)(templatePath, "utf-8");
+    return template.replace("{{REPO_OVERVIEW}}", overview);
+}
+function buildContentInline(overview) {
+    return [
         "# Polaris Rules",
         "",
         "> This file is the single shared governance source for this Polaris-managed repository.",
@@ -130,6 +128,28 @@ async function generatePolarisRules(repoRoot, inventory, options = {}) {
         "",
         "---",
         "",
+        "## Graph Navigation",
+        "",
+        "Polaris maintains a code-intelligence graph for this repository.",
+        "Use Polaris graph commands as the primary code-intelligence path.",
+        "Fall back to `rg` (ripgrep) and direct file inspection when the graph is unavailable.",
+        "",
+        "Primary commands:",
+        "```",
+        "polaris graph build",
+        "polaris graph query <symbol-or-file>",
+        "polaris graph impact <symbol-or-file>",
+        "polaris map query <path>",
+        "```",
+        "",
+        "Fallback (graph unavailable):",
+        "- `rg <pattern>` for symbol and pattern search",
+        "- Direct file inspection for structure and content",
+        "",
+        "Never prefer an external repo-analysis tool over Polaris graph for Polaris-managed repos.",
+        "",
+        "---",
+        "",
         "## Tracker-Agnostic Work Intake",
         "",
         "Work identifiers are opaque to the model. Polaris is tracker-agnostic.",
@@ -165,6 +185,22 @@ async function generatePolarisRules(repoRoot, inventory, options = {}) {
         "Do not assume global repository context unless explicitly provided by the runtime.",
         "",
     ].join("\n");
+}
+async function generatePolarisRules(repoRoot, inventory, options = {}) {
+    const { overwrite = false, workspaceDir } = options;
+    const outputPath = (0, node_path_1.join)(repoRoot, "POLARIS_RULES.md");
+    if ((0, node_fs_1.existsSync)(outputPath) && !overwrite) {
+        return;
+    }
+    const overview = buildRepoOverview(inventory);
+    let content;
+    const templatePath = workspaceDir ? (0, node_path_1.join)(workspaceDir, "POLARIS_RULES.md") : undefined;
+    if (templatePath && (0, node_fs_1.existsSync)(templatePath)) {
+        content = buildContentFromTemplate(templatePath, overview);
+    }
+    else {
+        content = buildContentInline(overview);
+    }
     const dir = (0, node_path_1.dirname)(outputPath);
     (0, node_fs_1.mkdirSync)(dir, { recursive: true });
     (0, node_fs_1.writeFileSync)(outputPath, content, "utf-8");

package/dist/cli/adopt-workspace.js

@@ -71,7 +71,7 @@ function buildAgentPointer() {
         "# Agent Instructions",
         "",
         "This repository is managed by Polaris.",
-        "Read [POLARIS.md](POLARIS.md) before beginning any work.",
+        "Read [POLARIS_RULES.md](POLARIS_RULES.md) before beginning any work.",
         "",
     ].join("\n");
 }
@@ -80,7 +80,7 @@ function buildCopilotPointer() {
         "# Copilot Instructions",
         "",
         "This repository is managed by Polaris.",
-        "Read [POLARIS.md](../../POLARIS.md) before beginning any work.",
+        "Read [POLARIS_RULES.md](../../POLARIS_RULES.md) before beginning any work.",
         "",
     ].join("\n");
 }

package/dist/cli/adoption-inventory.js

@@ -204,7 +204,9 @@ function detectAgentInstructionFiles(repoRoot, entries, doctrineExists) {
             return null;
         }
         const content = safeRead((0, node_path_1.join)(repoRoot, entry.path));
-        const hasPolarisDelegation = content.includes("<!-- polaris:delegate") || content.toLowerCase().includes("polaris.md");
+        const hasPolarisDelegation = content.includes("<!-- polaris:delegate") ||
+            content.toLowerCase().includes("polaris.md") ||
+            content.includes("POLARIS_RULES.md");
         const recommendation = recommendationForInstruction(hasPolarisDelegation, doctrineExists, entry.sizeBytes);
         return {
             path: entry.path,
@@ -322,7 +324,8 @@ function scanAdoptionInventory(repoRoot, options = {}) {
     const generatedRoots = detectRoots(allEntries, GENERATED_ROOT_HINTS);
     const cacheRoots = detectRoots(allEntries, CACHE_ROOT_HINTS);
     const fixtureRoots = detectRoots(allEntries, FIXTURE_ROOT_HINTS);
-    const doctrineExists = (0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "POLARIS.md"));
+    const doctrineExists = (0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "POLARIS.md")) ||
+        (0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, "POLARIS_RULES.md"));
     const inventory = {
         scan_date: now.toISOString(),
         repo_state: detectRepoState(repoRoot, topLevelEntries),

package/dist/cli/init.js

@@ -498,13 +498,14 @@ async function runInit(options = {}) {
     }
     void (options.generateFolderCognition ?? adopt_cognition_js_1.generateFolderCognition)(adoptionArtifacts.plan, inventory, repoRoot);
     process.stdout.write("Folder cognition generation step completed.\n");
-    (0, adopt_instructions_js_1.handleInstructionFiles)(adoptionArtifacts.plan, inventory, repoRoot);
-    process.stdout.write("Instruction file handling step completed.\n");
-    // Phase B — install bundled workspace assets
+    // Phase B — install bundled workspace assets (including POLARIS_RULES.md) before instruction
+    // file handling so that hasDoctrine() sees POLARIS_RULES.md during instruction classification.
     const installFn = options.installWorkspaceAssets ?? adopt_assets_js_1.installWorkspaceAssets;
     const workspaceDir = (0, node_path_1.resolve)(__dirname, "../workspace");
     const installResult = installFn(repoRoot, workspaceDir);
     process.stdout.write(`Workspace assets installed: ${installResult.installed.length} installed, ${installResult.alreadyPresent.length} already present.\n`);
+    const instructionResults = await (0, adopt_instructions_js_1.handleInstructionFiles)(adoptionArtifacts.plan, inventory, repoRoot);
+    process.stdout.write("Instruction file handling step completed.\n");
     const finalizeAdoptionFn = options.finalizeAdoption ?? finalizeAdoption;
     if (adoptionArtifacts.plan.steps.some((step) => step.category === "stage")) {
         await finalizeAdoptionFn(adoptionArtifacts.plan, {
@@ -521,7 +522,7 @@ async function runInit(options = {}) {
     const reconcileFn = options.reconcileAgentFiles ?? adopt_genesis_js_1.reconcileAgentFiles;
     const agentResults = await reconcileFn(repoRoot);
     // Phase E — adoption report
-    const adoptReport = (0, adopt_report_js_1.buildAdoptionReport)({ install: installResult, graph: graphResult, agents: agentResults });
+    const adoptReport = (0, adopt_report_js_1.buildAdoptionReport)({ install: installResult, graph: graphResult, agents: agentResults, instructionMigration: instructionResults });
     (0, adopt_report_js_1.printAdoptionReport)(adoptReport);
     (0, adopt_report_js_1.writeAdoptionReport)(repoRoot, adoptReport);
     // Phase F — safe stage + optional commit

package/dist/config/provider-detect.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectCaveman = detectCaveman;
 exports.detectGitNexus = detectGitNexus;
 exports.detectCompactionProviders = detectCompactionProviders;
+exports.detectPolarisGraph = detectPolarisGraph;
 exports.detectRepoAnalysisProviders = detectRepoAnalysisProviders;
 const node_fs_1 = require("node:fs");
 const node_child_process_1 = require("node:child_process");
@@ -50,11 +51,27 @@ function detectCompactionProviders(repoRoot) {
     }
     return detected;
 }
+/**
+ * Detects whether the Polaris graph provider is available.
+ *
+ * Polaris graph is considered present when the `polaris` executable is
+ * found on PATH (cross-platform: uses `where` on Windows, `which` on Unix).
+ */
+function detectPolarisGraph() {
+    try {
+        const command = process.platform === "win32" ? "where" : "which";
+        (0, node_child_process_1.execFileSync)(command, ["polaris"], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Runs repo-analysis provider detection and returns detected provider IDs.
  *
- * Recognised repo-analysis provider names: "gitnexus".
+ * Recognised repo-analysis provider names: "polaris-graph".
  */
 function detectRepoAnalysisProviders() {
-    return detectGitNexus() ? ["gitnexus"] : [];
+    return detectPolarisGraph() ? ["polaris-graph"] : [];
 }

package/dist/workspace/.polaris/skills/ROUTING.md

@@ -33,6 +33,10 @@ message whose primary instruction is to invoke a named Polaris skill.
 | `run polaris-status` | polaris-tools | `.polaris/skills/polaris-tools/` |
 | `docs-ingest` | docs-ingest | `.polaris/skills/docs-ingest/` |
 | `run docs-ingest` | docs-ingest | `.polaris/skills/docs-ingest/` |
+| `docs-triage` | docs-triage | `.polaris/skills/docs-triage/` |
+| `run docs-triage` | docs-triage | `.polaris/skills/docs-triage/` |
+| `docs-review` | docs-review | `.polaris/skills/docs-review/` |
+| `run docs-review` | docs-review | `.polaris/skills/docs-review/` |
 | `polaris-reconcile <CLUSTER-ID>` | polaris-reconcile | `.polaris/skills/polaris-reconcile/` |
 | `run polaris-reconcile on [issue] <CLUSTER-ID>` | polaris-reconcile | `.polaris/skills/polaris-reconcile/` |
 | `polaris-catalog <CLUSTER-ID>` | polaris-catalog | `.polaris/skills/polaris-catalog/` |

package/dist/workspace/.polaris/skills/closeout-librarian/POLARIS.md

@@ -14,13 +14,14 @@ per completed cluster, after all children are done and before PR creation.
 | `SKILL.md` | Skill entry point — read first, contains bootloader instructions and packet schema reference |
 | `chain.md` | Step-order execution map — the Librarian executes this in strict step order |
 | `steps/01-load-cluster-context.md` | Build work inventory from packet and cluster evidence |
-| `steps/02-reconcile-polaris-md.md` | Update affected POLARIS.md files |
-| `steps/03-reconcile-summary-md.md` | Refresh SUMMARY.md as continuation artifact |
-| `steps/04-doc-ingestion.md` | Ingest/promote/archive documentation |
-| `steps/05-link-validation.md` | Validate and repair broken links |
-| `steps/06-yaml-linking.md` | Update YAML references for promoted documents |
-| `steps/07-librarian-commit.md` | Commit documentation changes |
-| `steps/08-sealed-result.md` | Write sealed result JSON and terminate |
+| `steps/02-drift-reconciliation.md` | Run formal drift reconciliation |
+| `steps/03-reconcile-polaris-md.md` | Update affected POLARIS.md files |
+| `steps/04-reconcile-summary-md.md` | Refresh SUMMARY.md as continuation artifact |
+| `steps/05-doc-ingestion.md` | Ingest/promote/archive documentation |
+| `steps/06-link-validation.md` | Validate and repair broken links |
+| `steps/07-yaml-linking.md` | Update YAML references for promoted documents |
+| `steps/08-librarian-commit.md` | Commit documentation changes |
+| `steps/09-sealed-result.md` | Write sealed result JSON and terminate |
 
 ## Invocation
 
@@ -29,7 +30,7 @@ step 08 of the `polaris-run` chain after cluster-complete is confirmed.
 
 The Foreman generates the packet via:
 ```bash
-npm run polaris -- librarian packet <cluster-id>
+polaris librarian packet <cluster-id>
 ```
 
 Then dispatches the Librarian as a bounded subagent session.

package/dist/workspace/.polaris/skills/docs-ingest/SKILL.md

@@ -12,7 +12,7 @@ role_file: .polaris/roles/librarian.md
 Run the following command:
 
 ```
-npm run polaris -- skill packet ingest
+polaris skill packet ingest
 ```
 
 - Do not begin work until a packet is returned.
@@ -62,7 +62,7 @@ No document may be written directly to `specs/active/`, `doctrine/active/`, `arc
 - Write new Smart Docs to root `docs/` — `smartdocs/` is the canonical target
 - Silently promote documents to `doctrine/active/`, `specs/active/`, `architecture/`, or `decisions/`
 - Mutate source files (`src/`, tests, config)
-- Call `npm run polaris -- loop continue` or `npm run polaris -- finalize`
+- Call `polaris loop continue` or `polaris finalize`
 - Suppress detected conflicts
 
 **Docs-ingest routes and classifies. It does not implement or promote without explicit approval.**

package/dist/workspace/.polaris/skills/docs-ingest/chain.md

@@ -16,7 +16,7 @@ Query runtime state before acting. Do not infer ingest scope or prior progress f
 Always use the repo-local Polaris CLI:
 
 ```
-npm run polaris -- docs ingest [--file <path>] [--batch <cluster-id>] [--dry-run]
+polaris docs ingest [--file <path>] [--batch <cluster-id>] [--dry-run]
 ```
 
 Drop zone: `smartdocs/raw/` — this is the single ingest entry point.

package/dist/workspace/.polaris/skills/docs-ingest/steps/04-place-and-link.md

@@ -21,9 +21,9 @@ Execute placements for all files that cleared steps 02–03. High-confidence, no
 3. **Check for existing file** at the target path. If a file already exists there: halt for that file and report. Do not overwrite without explicit approval.
 
 4. **Use the Polaris CLI** — do not move files manually. The CLI handles provenance, map updates, and duplicate detection:
-   - `spec-raw` or low-confidence fallback: `npm run polaris -- docs ingest --file <path>` (CLI routes to `smartdocs/raw/`; if source is already there, no move occurs)
-   - `doctrine-candidate`: `npm run polaris -- doctrine draft <path>`
-   - All other classifications: use `npm run polaris -- docs ingest --file <path>`
+   - `spec-raw` or low-confidence fallback: `polaris docs ingest --file <path>` (CLI routes to `smartdocs/raw/`; if source is already there, no move occurs)
+   - `doctrine-candidate`: `polaris doctrine draft <path>`
+   - All other classifications: use `polaris docs ingest --file <path>`
    - If source is already in `smartdocs/` (reclassification): update front-matter only, re-run ingest to refresh provenance.
    - Do not write anything to root `docs/`.
 
@@ -37,7 +37,7 @@ Execute placements for all files that cleared steps 02–03. High-confidence, no
 
 6. **Provenance record** — the CLI writes `<filename>.provenance.json` alongside the placed file automatically. Verify it exists after placement.
 
-7. **Update Polaris map** — the CLI calls `updateMapEntry` internally. After the batch: run `npm run polaris -- map update --changed` to synchronize the atlas.
+7. **Update Polaris map** — the CLI calls `updateMapEntry` internally. After the batch: run `polaris map update --changed` to synchronize the atlas.
 
 ## Hard rules
 
@@ -58,7 +58,7 @@ allowed_files:
 expected_evidence:
   - all approved files placed at correct target paths within smartdocs/
   - provenance records written alongside each placed file
-  - map updated via npm run polaris -- map update --changed
+  - map updated via polaris map update --changed
   - low-confidence files confirmed routed to smartdocs/raw/
   - no placements to root docs/ or high-authority paths without approval
 stop_rules:

package/dist/workspace/.polaris/skills/docs-ingest/steps/05-finalize-ingest.md

@@ -37,7 +37,7 @@ Close out the ingest session cleanly. Emit telemetry. Write final state. Report.
 
 5. **Bootstrap packet** — if more clusters remain pending in `.polaris/docs-ingest/`, emit guidance for the next session:
    ```text
-   Next: npm run polaris -- docs ingest --batch <next-cluster-id>
+   Next: polaris docs ingest --batch <next-cluster-id>
    ```
 
 ## Completion rule

package/dist/workspace/.polaris/skills/docs-promote/SKILL.md

@@ -27,7 +27,7 @@ stop and use `polaris-catalog <POL-###>` instead.
 Run the following command:
 
 ```
-npm run polaris -- skill packet promote
+polaris skill packet promote
 ```
 
 - Do not begin work until a packet is returned.
@@ -61,10 +61,10 @@ Use this skill when documents have been ingested and need to be reviewed for pro
 - Read `smartdocs/raw/` and `smartdocs/doctrine/candidate/` to identify promotion candidates
 - Read linked source files (from `linkedMapArea` in provenance sidecar) to verify relevance and staleness
 - Read `smartdocs/doctrine/active/` and `smartdocs/specs/active/` to check for conflicts
-- Call `npm run polaris -- doctrine spec-promote <path>` to surface the conflict report (without `--approve`)
-- Call `npm run polaris -- doctrine spec-promote <path> --approve` **only after** surfacing the report and receiving explicit user confirmation
-- Call `npm run polaris -- doctrine promote <path>` for doctrine candidates that pass governance checks
-- Call `npm run polaris -- doctrine deprecate <path>` for active docs that are superseded or stale
+- Call `polaris doctrine spec-promote <path>` to surface the conflict report (without `--approve`)
+- Call `polaris doctrine spec-promote <path> --approve` **only after** surfacing the report and receiving explicit user confirmation
+- Call `polaris doctrine promote <path>` for doctrine candidates that pass governance checks
+- Call `polaris doctrine deprecate <path>` for active docs that are superseded or stale
 - Emit telemetry events
 
 ## Hard rules — what docs-promote must NOT do
@@ -72,7 +72,7 @@ Use this skill when documents have been ingested and need to be reviewed for pro
 - Auto-promote without surfacing the conflict report first
 - Call `--approve` without explicit user confirmation in the session
 - Mutate source files (`src/`, tests, config)
-- Call `npm run polaris -- loop continue` or `npm run polaris -- finalize`
+- Call `polaris loop continue` or `polaris finalize`
 - Promote to `architecture/` or `decisions/` — those require explicit ADR process
 - Suppress or ignore detected conflicts
 

package/dist/workspace/.polaris/skills/docs-promote/chain.md

@@ -30,11 +30,11 @@ Read the current step's file in `steps/` before acting. Do not read ahead.
 Always use the repo-local Polaris CLI:
 
 ```
-npm run polaris -- doctrine draft <path>
-npm run polaris -- doctrine promote <path>
-npm run polaris -- doctrine deprecate <path>
-npm run polaris -- doctrine spec-promote <path>
-npm run polaris -- doctrine spec-promote <path> --approve
+polaris doctrine draft <path>
+polaris doctrine promote <path>
+polaris doctrine deprecate <path>
+polaris doctrine spec-promote <path>
+polaris doctrine spec-promote <path> --approve
 ```
 
 Never assume a globally linked `polaris` command exists.

package/dist/workspace/.polaris/skills/docs-promote/steps/04-conflict-surface.md

@@ -16,7 +16,7 @@ Surface every conflict before asking for approval. The agent must not approve an
 Run the dry gate for each:
 
 ```bash
-npm run polaris -- doctrine spec-promote <path>
+polaris doctrine spec-promote <path>
 ```
 
 Capture the full stdout. This is the conflict report. Do **not** pass `--approve`.

package/dist/workspace/.polaris/skills/docs-promote/steps/06-execute-promote-deprecate.md

@@ -15,17 +15,17 @@ For each candidate with `decision: approved`:
 
 ### Spec promotion
 ```bash
-npm run polaris -- doctrine spec-promote <path> --approve
+polaris doctrine spec-promote <path> --approve
 ```
 
 ### Doctrine candidate promotion
 ```bash
-npm run polaris -- doctrine promote <path>
+polaris doctrine promote <path>
 ```
 
 ### Active doctrine deprecation
 ```bash
-npm run polaris -- doctrine deprecate <path>
+polaris doctrine deprecate <path>
 ```
 
 After each command:

package/dist/workspace/{workspace/.polaris → .polaris}/skills/docs-review/SKILL.md

@@ -12,7 +12,7 @@ role_file: .polaris/roles/librarian.md
 Run the following command:
 
 ```
-npm run polaris -- skill packet review
+polaris skill packet review
 ```
 
 - Do not begin work until a packet is returned.

package/dist/workspace/{workspace/.polaris → .polaris}/skills/docs-triage/SKILL.md

@@ -12,7 +12,7 @@ role_file: .polaris/roles/librarian.md
 Run the following command:
 
 ```
-npm run polaris -- skill packet triage
+polaris skill packet triage
 ```
 
 - Do not begin work until a packet is returned.

package/dist/workspace/{workspace/.polaris → .polaris}/skills/docs-triage/chain.md

@@ -16,7 +16,7 @@ Query runtime state before acting. Do not infer triage scope or prior progress f
 Always use the repo-local Polaris CLI:
 
 ```
-npm run polaris -- docs triage [--dry-run] [--batch-size <n>] [--resume] [--repo-root <path>]
+polaris docs triage [--dry-run] [--batch-size <n>] [--resume] [--repo-root <path>]
 ```
 
 - `--dry-run`: prints cluster count, estimated batches, estimated tokens, and model — no LLM calls

package/dist/workspace/.polaris/skills/polaris-analyze/SKILL.md

@@ -26,7 +26,7 @@ protocol.
 Run the following command:
 
 ```
-npm run polaris -- skill packet analyze
+polaris skill packet analyze
 ```
 
 - Do not begin work until a packet is returned.