@a-company/paradigm 3.1.5 → 3.5.0

package/dist/university-content/reference.json

@@ -141,6 +141,55 @@
           "when": "After creating or modifying aspects, or when paradigm doctor reports stale anchors.",
           "example": "paradigm_aspect_check({ aspect: '~audit-required' })"
         },
+        {
+          "id": "paradigm-aspect-search",
+          "name": "paradigm_aspect_search",
+          "description": "Search aspects using three-tier learning search (learned mappings → FTS5 → fuzzy). Returns ranked results with scores and tiers. Call paradigm_aspect_confirm after selecting a result to improve future searches.",
+          "when": "When looking for aspects by keyword, description, or related concept. The search improves over time as you confirm results.",
+          "example": "paradigm_aspect_search({ query: 'jwt expiry' })"
+        },
+        {
+          "id": "paradigm-aspect-get",
+          "name": "paradigm_aspect_get",
+          "description": "Get full aspect details — description, category, severity, code anchor snippets, graph edges, and linked lore entries.",
+          "when": "After finding an aspect via search, to see its full context including the actual code at anchor locations.",
+          "example": "paradigm_aspect_get({ aspectId: 'token-expiry-24h' })"
+        },
+        {
+          "id": "paradigm-aspect-graph",
+          "name": "paradigm_aspect_graph",
+          "description": "Get the subgraph neighborhood of a symbol — all aspects and edges within N hops.",
+          "when": "When exploring how aspects relate to each other and to symbols in the codebase.",
+          "example": "paradigm_aspect_graph({ symbol: '~token-expiry-24h', hops: 2 })"
+        },
+        {
+          "id": "paradigm-aspect-heatmap",
+          "name": "paradigm_aspect_heatmap",
+          "description": "Get most-accessed aspects ranked by usage frequency, broken down by access type (search, ripple, navigate, direct).",
+          "when": "To understand which aspects are most frequently referenced and which might be under-utilized.",
+          "example": "paradigm_aspect_heatmap({ limit: 10 })"
+        },
+        {
+          "id": "paradigm-aspect-suggest-scan",
+          "name": "paradigm_aspect_suggest_scan",
+          "description": "Scan a source file for undocumented aspects — magic numbers, hardcoded strings, rate limits, time values, env checks, feature flags, and regex patterns.",
+          "when": "When auditing a file for rules and constraints that should be documented as aspects.",
+          "example": "paradigm_aspect_suggest_scan({ filePath: 'src/auth/jwt.ts' })"
+        },
+        {
+          "id": "paradigm-aspect-drift",
+          "name": "paradigm_aspect_drift",
+          "description": "Check aspect anchors for content drift — detects when code at anchored line ranges has changed since the last scan.",
+          "when": "During maintenance to find stale anchors, or after significant refactoring to verify aspect integrity.",
+          "example": "paradigm_aspect_drift({ aspectId: 'token-expiry-24h' })"
+        },
+        {
+          "id": "paradigm-aspect-confirm",
+          "name": "paradigm_aspect_confirm",
+          "description": "Confirm a search result to improve future search quality. Reinforces the query-to-aspect mapping in the learning system.",
+          "when": "After selecting a result from paradigm_aspect_search. This is how the search gets smarter over time.",
+          "example": "paradigm_aspect_confirm({ query: 'jwt expiry', aspectId: 'token-expiry-24h' })"
+        },
         {
           "id": "paradigm-purpose-validate",
           "name": "paradigm_purpose_validate",
@@ -196,6 +245,67 @@
           "description": "Save a session checkpoint for crash recovery. Captures phase, context, modified files, symbols, and decisions. Stored in .paradigm/session-checkpoint.json with 7-day expiry.",
           "when": "At every phase transition — after planning, during implementation, before validation, and on completion.",
           "example": "paradigm_session_checkpoint({ phase: 'implementing', context: 'Adding JWT auth middleware', modifiedFiles: ['src/middleware/auth.ts'], symbolsTouched: ['#auth-middleware'] })"
+        },
+        {
+          "id": "paradigm-sentinel-record",
+          "name": "paradigm_sentinel_record",
+          "description": "Record a symbolic incident mapping a runtime error to Paradigm symbols. Captures error details, symbolic context, environment, and optional flow position.",
+          "when": "When an error occurs and you want to track it in Sentinel with full symbolic context for pattern matching and triage.",
+          "example": "paradigm_sentinel_record({ error: { message: 'Stripe 429', type: 'RateLimitError' }, symbols: { component: '#payment-service' }, environment: 'production' })"
+        }
+      ]
+    },
+    {
+      "id": "habit-check-types",
+      "title": "Habit Check Types",
+      "cards": [
+        {
+          "id": "tool-called",
+          "name": "tool-called",
+          "description": "Verifies that specified MCP tools were invoked during the session. Any one tool from the list suffices.",
+          "when": "For discovery habits (ripple, navigate), collaboration habits (wisdom), and verification habits (postflight)."
+        },
+        {
+          "id": "file-exists",
+          "name": "file-exists",
+          "description": "Verifies that files matching glob patterns exist. Used for .purpose file coverage and test existence.",
+          "when": "For documentation habits (.purpose coverage) and testing habits (test file existence)."
+        },
+        {
+          "id": "lore-recorded",
+          "name": "lore-recorded",
+          "description": "Verifies a lore entry was created during sessions that modify 3+ source files.",
+          "when": "For documentation habits that enforce lore recording for significant sessions."
+        },
+        {
+          "id": "gates-declared",
+          "name": "gates-declared",
+          "description": "Verifies routes added during the session have corresponding gate declarations in portal.yaml.",
+          "when": "For security habits that ensure every API endpoint has authorization gates."
+        },
+        {
+          "id": "commit-message-format",
+          "name": "commit-message-format",
+          "description": "Verifies commit messages match required regex patterns — default: conventional commit type(#symbol): prefix and Symbols: trailer.",
+          "when": "On-commit trigger to enforce consistent, symbol-aware commit messages."
+        },
+        {
+          "id": "flow-coverage",
+          "name": "flow-coverage",
+          "description": "Verifies that changes spanning 3+ components have a documented $flow or that flow tools were invoked.",
+          "when": "Postflight trigger to ensure multi-component changes are documented as flows."
+        },
+        {
+          "id": "context-checked",
+          "name": "context-checked",
+          "description": "Verifies that session context/recovery tools (paradigm_context_check, paradigm_session_recover, paradigm_session_checkpoint) were called.",
+          "when": "Preflight trigger to encourage session continuity and context awareness."
+        },
+        {
+          "id": "aspect-anchored",
+          "name": "aspect-anchored",
+          "description": "Verifies that aspects (~) touched during the session have valid code anchors via paradigm_aspect_check.",
+          "when": "Postflight trigger to ensure aspect anchors remain valid after code changes."
         }
       ]
     },
@@ -268,6 +378,36 @@
           "command": "paradigm lore <subcommand>",
           "description": "Manage project lore — the timeline of sessions, decisions, milestones, and incidents. Subcommands: list (show recent entries), show (display a specific entry), record (create a new entry interactively), review (add review scores to an entry).",
           "flags": ["list [--limit 10] [--type agent-session]: List recent entries", "show <id>: Display a specific lore entry", "record [--type agent-session]: Record a new entry", "review <id>: Add completeness and quality scores to an entry"]
+        },
+        {
+          "id": "portal-export",
+          "command": "paradigm portal export",
+          "description": "Export portal configuration in machine-readable formats. Outputs gates and routes for CI audits, documentation, or spreadsheet analysis.",
+          "flags": ["-f, --format <format>: Output format — json (default), csv, markdown", "-o, --output <file>: Write to file instead of stdout", "-c, --config <path>: Path to portal.yaml (default: ./portal.yaml)"]
+        },
+        {
+          "id": "lint",
+          "command": "paradigm lint",
+          "description": "Check .purpose files for completeness — validates required fields, symbol formatting, tag references. With --auto-populate, scans source directories for undocumented components and suggests draft .purpose files.",
+          "flags": ["--fix: Auto-fix lint issues (or write draft .purpose files with --auto-populate)", "--strict: Treat warnings as errors", "--auto-populate: Scan source dirs for undocumented components and suggest .purpose drafts"]
+        },
+        {
+          "id": "sync-llms",
+          "command": "paradigm sync-llms",
+          "description": "Generate llms.txt at the project root — a plain-text project summary optimized for LLM consumption. Includes symbols, key files, flows, gates, and conventions.",
+          "flags": ["-o, --output <path>: Output path (default: ./llms.txt)"]
+        },
+        {
+          "id": "flow-diagram",
+          "command": "paradigm flow diagram <flowId>",
+          "description": "Generate a Mermaid flowchart diagram for a flow. Gates appear as diamonds, actions as rectangles, signals as rounded boxes. Color-coded by step type.",
+          "flags": ["-o, --output <path>: Write diagram to file instead of stdout"]
+        },
+        {
+          "id": "global-clean",
+          "command": "paradigm global clean",
+          "description": "Remove old files from ~/.paradigm/ (Global Brain rotation). Scans wisdom, lore, history, and cache subdirectories for files older than the specified duration.",
+          "flags": ["--older-than <duration>: Duration threshold (default: 90d). Supports d (days), h (hours), m (minutes)", "-n, --dry-run: Show what would be deleted without deleting"]
         }
       ]
     },
@@ -392,6 +532,136 @@
           ]
         }
       ]
+    },
+    {
+      "id": "aspect-categories",
+      "title": "Aspect Categories",
+      "cards": [
+        {
+          "id": "category-rule",
+          "name": "rule",
+          "description": "A mandatory pattern that must be followed across the codebase. Rules are non-negotiable constraints enforced by code. Inferred from descriptions containing 'must', 'always', 'never', 'required'.",
+          "examples": ["~no-console-log", "~audit-required", "~idempotent-payments"],
+          "when": "When a pattern must be followed without exception — if violating it would be a bug or compliance issue."
+        },
+        {
+          "id": "category-decision",
+          "name": "decision",
+          "description": "An architectural or design choice with documented rationale. Decisions capture the 'why' behind implementation choices. Inferred from descriptions containing 'decided', 'chosen', 'selected', 'opted'.",
+          "examples": ["~use-redis-for-sessions", "~jwt-signing-rs256", "~monorepo-structure"],
+          "when": "When a deliberate choice was made between alternatives and the rationale should be preserved for future reference."
+        },
+        {
+          "id": "category-constraint",
+          "name": "constraint",
+          "description": "A quantitative limit or boundary on system behavior. Constraints define the numeric or measurable boundaries of operations. Inferred from descriptions containing 'limit', 'maximum', 'minimum', 'cannot exceed'.",
+          "examples": ["~max-upload-10mb", "~rate-limit-100-per-minute", "~session-timeout-30m"],
+          "when": "When a measurable boundary exists — file size limits, rate limits, timeouts, quotas, or thresholds."
+        },
+        {
+          "id": "category-configuration",
+          "name": "configuration",
+          "description": "A configurable value or setting that controls system behavior. Configuration aspects document values that may change per environment. Inferred from descriptions containing 'configured', 'set to', 'defaults to', 'environment'.",
+          "examples": ["~default-page-size-25", "~cache-ttl-5m", "~feature-flag-new-checkout"],
+          "when": "When a value is environment-specific or tunable — defaults, feature flags, environment variables, or deployment settings."
+        },
+        {
+          "id": "category-invariant",
+          "name": "invariant",
+          "description": "A condition that must always hold true in the system. Invariants are guarantees about system state that should never be violated. Inferred from descriptions containing 'always true', 'never negative', 'invariant', 'guarantee'.",
+          "examples": ["~balance-never-negative", "~user-always-has-email", "~order-total-matches-items"],
+          "when": "When a system property must hold at all times — data integrity rules, mathematical invariants, or state consistency guarantees."
+        }
+      ]
+    },
+    {
+      "id": "aspect-edge-relations",
+      "title": "Aspect Edge Relations",
+      "cards": [
+        {
+          "id": "edge-enforced-by",
+          "name": "enforced-by",
+          "description": "Indicates that an aspect is enforced by another symbol — typically a component, middleware, or gate that implements the rule in code. The target symbol contains the enforcement logic.",
+          "examples": ["~audit-required --enforced-by--> #audit-middleware", "~rate-limited --enforced-by--> ^rate-limiter"],
+          "when": "When an aspect has a concrete enforcement mechanism in code. This is the most common edge type for rules and constraints."
+        },
+        {
+          "id": "edge-depends-on",
+          "name": "depends-on",
+          "description": "Indicates that an aspect depends on another aspect or symbol for its correct functioning. If the dependency changes, the dependent aspect may need updating.",
+          "examples": ["~token-expiry-24h --depends-on--> ~jwt-signing-rs256", "~cache-invalidation --depends-on--> #event-bus"],
+          "when": "When changing one aspect could break or invalidate another. The ripple analysis follows these edges to discover indirect impacts."
+        },
+        {
+          "id": "edge-contradicts",
+          "name": "contradicts",
+          "description": "Indicates that two aspects are in tension or direct conflict. Contradictions signal architectural tensions that need resolution or documented trade-offs.",
+          "examples": ["~cache-aggressively --contradicts--> ~always-fresh-data", "~minimal-logging --contradicts--> ~full-audit-trail"],
+          "when": "When two aspects cannot both be fully satisfied simultaneously. Documenting contradictions makes trade-offs visible rather than hidden."
+        },
+        {
+          "id": "edge-supersedes",
+          "name": "supersedes",
+          "description": "Indicates that an aspect replaces or overrides a previous version. The superseded aspect is still referenced for history but the superseding one is authoritative.",
+          "examples": ["~rate-limit-v2 --supersedes--> ~rate-limit-v1", "~auth-jwt --supersedes--> ~auth-session-cookie"],
+          "when": "When an aspect evolves and a newer version replaces the old one. Keeps the historical chain visible while directing users to the current version."
+        },
+        {
+          "id": "edge-related-to",
+          "name": "related-to",
+          "description": "The weakest relation — indicates a loose association between two symbols. Useful for discovery but not for impact analysis. Does not imply dependency or enforcement.",
+          "examples": ["~password-policy --related-to--> ~account-lockout", "~api-versioning --related-to--> ~deprecation-strategy"],
+          "when": "When two aspects are conceptually related but do not have a stronger structural relationship like enforcement or dependency."
+        }
+      ]
+    },
+    {
+      "id": "configurable-limits",
+      "title": "Configurable Limits",
+      "cards": [
+        {
+          "id": "limits-overview",
+          "name": "limits in config.yaml",
+          "description": "Paradigm supports configurable limits in .paradigm/config.yaml under a `limits` key. These tune cache TTLs, breadcrumb retention, and checkpoint lifetimes.",
+          "when": "When default values don't fit your workflow — e.g., longer cache TTL for stable projects, shorter checkpoint expiry for fast-moving teams."
+        },
+        {
+          "id": "habits-cache-ttl",
+          "name": "habitsCacheTtlMs",
+          "description": "Habits cache TTL in milliseconds. Controls how long loaded habit definitions are cached before being re-read from YAML files. Default: 30000 (30 seconds).",
+          "when": "Set higher for stable habit configs; set to 0 to always re-read."
+        },
+        {
+          "id": "tool-cache-ttl",
+          "name": "toolCacheTtlMs",
+          "description": "MCP tool cache TTL in milliseconds. Controls how long paradigm_search, paradigm_status, and paradigm_navigate results are cached. Default: 30000 (30 seconds).",
+          "when": "Set higher for large, stable projects; set to 0 to disable caching."
+        },
+        {
+          "id": "thread-trail-max",
+          "name": "threadTrailMax",
+          "description": "Maximum thread trail/breadcrumb entries retained in thread output. Default: 10.",
+          "when": "Increase for complex sessions that need more trail context."
+        },
+        {
+          "id": "breadcrumbs-max",
+          "name": "breadcrumbsMax",
+          "description": "Maximum session breadcrumbs retained by the session tracker. Default: 50.",
+          "when": "Increase for very long sessions; decrease to reduce checkpoint file size."
+        },
+        {
+          "id": "checkpoint-max-age",
+          "name": "checkpointMaxAgeMs",
+          "description": "Maximum age of session checkpoints before they expire. Default: 604800000 (7 days).",
+          "when": "Shorten for teams that don't want stale recovery data; lengthen for projects with infrequent sessions."
+        },
+        {
+          "id": "aspect-search-decay",
+          "name": "Search Weight Decay",
+          "description": "When a search result is confirmed, the selected aspect gets +1.0 weight while all other results for the same query decay by *0.95. This self-correcting mechanism prevents stale mappings.",
+          "when": "Automatic — happens on every paradigm_aspect_confirm call."
+        }
+      ]
     }
   ]
 }

package/dist/{upgrade-TIYFQYPO.js → upgrade-RBSE4M6I.js}

@@ -3,7 +3,7 @@ import {
   detectIDE,
   loadParadigmFiles,
   syncToIDE
-} from "./chunk-YCLN7WXV.js";
+} from "./chunk-2QNZ6PVD.js";
 import {
   parseParadigmConfig,
   serializeParadigmConfig

package/dist/{validate-QEEY6KFS.js → validate-2LTHHORX.js}

@@ -3,7 +3,7 @@ import {
   formatValidationResult,
   getAllPurposeFiles,
   validatePurposeFile
-} from "./chunk-PW2EXJQT.js";
+} from "./chunk-MRENOFTR.js";
 import "./chunk-MO4EEYFW.js";
 
 // src/commands/purpose/validate.ts

package/dist/{watch-4LT4O6K7.js → watch-NBPOMOEX.js}

@@ -117,7 +117,83 @@ async function portalReportCommand(sessionPath, options = {}) {
     process.exit(1);
   }
 }
+async function portalExportCommand(targetPath, options = {}) {
+  const rootDir = targetPath ? path.resolve(targetPath) : process.cwd();
+  const configPath = options.config || path.join(rootDir, "portal.yaml");
+  const format = options.format || "json";
+  if (!fs.existsSync(configPath)) {
+    console.error(chalk.red(`portal.yaml not found at ${configPath}`));
+    process.exit(1);
+  }
+  const { parse } = await import("./dist-JOHRYQUA.js");
+  const raw = fs.readFileSync(configPath, "utf8");
+  const config = parse(raw);
+  const gates = config.gates || {};
+  const routes = config.routes || {};
+  let output;
+  switch (format) {
+    case "csv": {
+      const lines = ["route,method,gates"];
+      for (const [routeKey, routeGates] of Object.entries(routes)) {
+        const parts = routeKey.split(" ");
+        const method = parts.length > 1 ? parts[0] : "ANY";
+        const routePath = parts.length > 1 ? parts.slice(1).join(" ") : routeKey;
+        const gateList = Array.isArray(routeGates) ? routeGates.join(";") : String(routeGates);
+        lines.push(`${routePath},${method},"${gateList}"`);
+      }
+      output = lines.join("\n");
+      break;
+    }
+    case "markdown": {
+      const lines = [
+        `# Portal Configuration`,
+        "",
+        `**Version:** ${config.version || "unknown"}`,
+        "",
+        "## Gates",
+        "",
+        "| Gate | Description | Check |",
+        "|------|-------------|-------|"
+      ];
+      for (const [gateId, gate] of Object.entries(gates)) {
+        const g = gate;
+        lines.push(`| ^${gateId} | ${g.description || ""} | \`${g.check || ""}\` |`);
+      }
+      lines.push("", "## Routes", "", "| Route | Gates |", "|-------|-------|");
+      for (const [routeKey, routeGates] of Object.entries(routes)) {
+        const gateList = Array.isArray(routeGates) ? routeGates.join(", ") : String(routeGates);
+        lines.push(`| ${routeKey} | ${gateList} |`);
+      }
+      output = lines.join("\n");
+      break;
+    }
+    case "json":
+    default: {
+      const exported = {
+        version: config.version,
+        exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        gates: Object.entries(gates).map(([id, g]) => ({
+          id,
+          ...g
+        })),
+        routes: Object.entries(routes).map(([route, routeGates]) => ({
+          route,
+          gates: routeGates
+        }))
+      };
+      output = JSON.stringify(exported, null, 2);
+      break;
+    }
+  }
+  if (options.output) {
+    fs.writeFileSync(options.output, output, "utf8");
+    console.log(chalk.green(`Exported portal config to ${chalk.cyan(options.output)} (${format})`));
+  } else {
+    console.log(output);
+  }
+}
 export {
+  portalExportCommand,
   portalReportCommand,
   portalWatchCommand
 };

package/dist/{watch-2XEYUH43.js → watch-PAEH6MOG.js}

@@ -3,7 +3,7 @@ import {
   detectIDE,
   loadParadigmFiles,
   syncToIDE
-} from "./chunk-YCLN7WXV.js";
+} from "./chunk-2QNZ6PVD.js";
 import "./chunk-YO6DVTL7.js";
 import "./chunk-MO4EEYFW.js";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a-company/paradigm",
-  "version": "3.1.5",
+  "version": "3.5.0",
   "description": "Unified CLI for Paradigm developer tools",
   "type": "module",
   "main": "./dist/index.js",