@rkarim08/sia 1.0.0

package/README.md

@@ -0,0 +1,1013 @@
+# Sia
+
+**Persistent graph memory for AI coding agents.**
+
+> *Sia was the Egyptian personification of perception, insight, and divine knowledge. She rode on the prow of Ra's solar barque and was said to write knowledge on the heart — the precise act of embedding structured understanding into a store that shapes all future reasoning.*
+
+Every time you close a Claude Code session, the agent forgets everything. Decisions made Monday are invisible Friday. Bugs analyzed last week get rediscovered from scratch. Conventions established over days must be re-explained. Across a month of daily development, this compounds into hours of lost effort — and across a team, the problem multiplies because each developer's agent independently rebuilds the same understanding.
+
+Sia captures knowledge from your sessions automatically and stores it in a local, bi-temporal knowledge graph. Between sessions, your agent retrieves only what is relevant. No explicit input. No server required. Everything runs locally.
+
+---
+
+## Why Sia?
+
+### The Problem: Agent Amnesia
+
+AI coding agents have no persistent memory. Each session starts from zero. The agent cannot recall why a decision was made, what was tried before, or what constraints the team has accumulated over months. Context windows are finite, and when they compact, even intra-session knowledge is lost.
+
+### The Solution: Persistent Knowledge Graph
+
+Sia gives your agent a typed, temporal, ontology-enforced knowledge graph that captures decisions, bugs, conventions, patterns, and the structural dependency graph of your codebase. Knowledge flows in automatically via hooks and out automatically via MCP tools. The developer never needs to manage the graph explicitly.
+
+### How Sia Differs from Existing Solutions
+
+| Capability | CLAUDE.md (manual) | claude-mem | Obsidian + plugins | **Sia** |
+|---|---|---|---|---|
+| **Storage model** | Flat text file | Key-value store | Markdown vault with wikilinks | Unified knowledge graph with typed nodes and edges |
+| **Relationships** | None — facts are isolated lines | None | Wikilinks (untyped, manual) | Typed, weighted edges (calls, supersedes, caused_by, solves, pertains_to, ...) |
+| **Ontology enforcement** | None | None | None — any link to any note | Declarative edge constraints — invalid relationships rejected at write time |
+| **Temporal awareness** | None — stale facts persist forever | Manual deletion | Git history (manual) | Bi-temporal: every fact has valid-from/valid-until; nothing is deleted, only invalidated |
+| **Time-travel queries** | Not possible | Not possible | Manual git checkout | `sia_at_time` queries the graph at any historical point |
+| **Retrieval** | Entire file injected every session | Keyword search | Full-text search + backlinks | Hybrid: vector similarity + BM25 + graph traversal with trust-weighted RRF reranking |
+| **Context cost** | Grows unbounded with project maturity | Grows with entries | Manual copy-paste to agent | ~1,200 tokens average per session (only relevant facts retrieved) |
+| **Code structure** | Not captured | Not captured | Not captured | AST-powered structural backbone via Tree-sitter (30+ languages) |
+| **Documentation ingestion** | Not captured | Not captured | Manual note creation | Auto-discovers and indexes AGENTS.md, CLAUDE.md, ADRs, README.md, and 15+ doc formats |
+| **Agent integration** | Injected at session start | MCP tool calls | None native; requires manual bridging | Native MCP server with 16 tools, automatic hook-based capture |
+| **Sandbox execution** | N/A | N/A | N/A | Isolated subprocess execution with context-aware output indexing |
+| **Session continuity** | Lost on compaction | Lost on compaction | N/A | Priority-weighted subgraph serialization survives context compaction |
+| **Knowledge authoring** | Developer writes manually | Developer writes manually | Developer writes manually (rich editor) | `sia_note` for deliberate entry + automatic dual-track capture |
+| **Multi-repo** | One file per repo, no cross-repo awareness | Single store, no repo concept | One vault, manual organization | Workspace model with cross-repo edges and API contract detection |
+| **Team sharing** | Copy-paste or shared file | Not supported | Git sync or Obsidian Sync ($) | Optional sync via self-hosted server with visibility controls |
+| **Security** | No write validation | No write validation | No trust model | 4-tier trust model, ontology enforcement, isolated staging area, paranoid mode, audit log with rollback |
+| **Scalability** | Collapses past ~50 entries | Linear degradation | Degrades past ~10K notes | SQLite-backed, tested to 50K nodes with sub-800ms retrieval |
+| **Capture method** | Developer writes manually | Developer writes manually | Developer writes manually | Automatic dual-track: deterministic AST + probabilistic LLM |
+| **Knowledge decay** | Manual cleanup | Manual cleanup | Manual cleanup | Automatic importance decay with configurable half-lives per node kind |
+| **Graph freshness** | Stale facts persist forever | No freshness model | No freshness model | Five-layer freshness engine: file-watcher, git-reconcile, stale-while-revalidate, confidence decay, deep validation |
+| **Visualization** | Not available | Not available | Graph view (built-in) | Interactive D3.js graph explorer |
+| **Export** | N/A | N/A | Native markdown | Obsidian-compatible markdown vault export/import (round-trip) |
+| **Native performance** | N/A | N/A | N/A | Optional Rust module via NAPI-RS (AST diffing, PageRank, Leiden) with Wasm and TypeScript fallbacks |
+| **Knowledge capture** | N/A | N/A | N/A | Three-layer: hooks (real-time, $0) + CLAUDE.md directives (proactive, $0) + pluggable LLM fallback |
+| **Cross-agent support** | Claude Code only | Claude Code only | N/A | Claude Code (native), Cursor, Cline (hook adapters), Windsurf/Aider (MCP-only fallback) |
+
+**The core difference:** CLAUDE.md and claude-mem treat memory as flat text or key-value stores. Obsidian provides rich manual knowledge management but has no AI agent integration. Sia treats memory as a **typed, temporal, ontology-enforced knowledge graph** with native agent integration — the same data structure that makes knowledge useful to humans also makes it useful to AI agents, and knowledge flows automatically between sessions without manual curation.
+
+---
+
+## Quick Start
+
+### Plugin Installation (Recommended)
+
+```bash
+# 1. Add the Sia marketplace (one-time)
+/plugin marketplace add rkarim08/sia
+
+# 2. Install the plugin
+/plugin install sia@sia-plugins
+```
+
+This registers all 21 MCP tools, 46 skills, 23 agents, 8 hooks, and CLAUDE.md behavioral directives in one step.
+
+> **Coming soon:** Once Sia is accepted into the official Anthropic marketplace, installation will simplify to `/plugin install sia@claude-plugins-official`.
+
+### Standalone Installation
+
+If you prefer CLI-only usage without the plugin system:
+
+```bash
+npx sia install
+```
+
+This takes under three minutes and creates the `~/.sia/` directory, downloads the embedding model (~90MB ONNX), indexes your repository, generates CLAUDE.md directives, and registers the MCP server.
+
+### Build the Knowledge Graph
+
+```bash
+/sia-learn                # Full build: install + index code + ingest docs + detect communities
+/sia-learn --incremental  # Update changed files only
+/sia-learn --force        # Full rebuild ignoring all caches
+```
+
+### First-Run Wizard
+
+```bash
+/sia-setup                # Guided setup: detect project, configure, learn, tour
+```
+
+### Verify It Works
+
+```bash
+sia stats                           # Graph statistics
+sia search "authentication"         # Search the knowledge graph
+sia doctor                          # Health check
+/sia-visualize-live                 # Graph explorer in your browser
+```
+
+---
+
+## How It Works
+
+### Write Path (Capture)
+
+```
+Claude Code session
+  |
+  hooks fire on every action
+  |
+  v
+PostToolUse ──┐
+Stop ─────────┤
+UserPrompt ───┤
+PreCompact ───┤
+SessionStart ─┘
+  |
+  v
+Hook capture ($0)       ──> Event nodes (EditEvent, ExecutionEvent, GitEvent, ...)
+Dual-track extraction   ──> Track A: AST (deterministic) + Track B: LLM (probabilistic)
+Ontology validation     ──> Edge constraints enforced at SQLite trigger level
+Two-phase consolidation ──> ADD / UPDATE / INVALIDATE / NOOP against existing graph
+Atomic write            ──> Single transaction with full audit log
+```
+
+### Read Path (Retrieval)
+
+```
+MCP tool call (sia_search, sia_by_file, ...)
+  |
+  v
+Vector similarity (ONNX embeddings + sqlite-vss)
+BM25 keyword search (SQLite FTS5)
+Graph traversal (1-hop expansion from mentioned nodes)
+  |
+  v
+Reciprocal Rank Fusion
+  weighted by: trust tier, task type, importance decay, graph proximity
+  |
+  v
+Progressive throttling: normal (calls 1-3), reduced (4-8), blocked (9+)
+  |
+  v
+Response to Claude Code
+```
+
+### Three-Layer Capture Architecture
+
+```
+Layer 1: Claude Code Hooks (real-time, deterministic, $0)
+  PostToolUse --> extracts knowledge from every Write, Edit, Bash, Read operation
+  Stop --> processes transcript for decisions expressed in natural language
+  PreCompact --> snapshots graph state before context compaction
+  SessionStart --> injects relevant graph context into new sessions
+
+Layer 2: CLAUDE.md Behavioral Directives (proactive, $0)
+  Claude calls sia_note when it makes architectural decisions
+  Claude calls sia_search before starting new tasks
+  Captures the "why" -- reasoning, alternatives, context
+
+Layer 3: Pluggable LLM Provider (offline + fallback)
+  Community summarization (requires full-graph reasoning)
+  Deep validation (maintenance sweep)
+  Non-Claude-Code agents (Cursor, Windsurf, Cline)
+  Built on Vercel AI SDK -- supports Anthropic, OpenAI, Google, Ollama
+```
+
+**Cost in practice:** ~$0.04/day vs ~$0.36/day for a pure-API approach. Hooks observe at the moment of maximum context, capturing richer knowledge at zero LLM cost.
+
+**Three capture modes** (configured in `sia.config.yaml`):
+- **`hooks`** (default for Claude Code): Real-time hook capture + LLM for offline operations only
+- **`api`** (fallback for non-Claude-Code agents): All extraction via pluggable LLM provider
+- **`hybrid`**: Hooks for real-time + LLM for batch operations
+
+### Auto-Integration via CLAUDE.md
+
+SIA injects behavioral directives into your project's CLAUDE.md that make Claude use the knowledge graph automatically:
+
+- **Task classification** -- Claude classifies each task (bug-fix, feature, review, orientation) and loads the corresponding playbook via `/sia-playbooks`
+- **Tool selection** -- `sia_search` before any non-trivial task, `sia_by_file` before modifying files, `sia_note` after decisions, `sia_at_time` for regressions
+- **Trust tier rules** -- Tier 1-2 facts cited as ground truth, Tier 3 qualified before acting, Tier 4 referenced only
+
+Knowledge flows into and out of the graph automatically during normal coding sessions.
+
+---
+
+## What Gets Captured
+
+Sia uses a unified graph with a `kind` discriminator. Nodes fall into three categories:
+
+### Structural Nodes (Code Backbone)
+
+| Kind | What It Represents | Example |
+|------|-------------------|---------|
+| **CodeSymbol** | Functions, classes, modules | `UserService.authenticate()` -- handles JWT validation |
+| **FileNode** | Source files and documentation files | `src/auth/service.ts` |
+| **PackageNode** | Packages in monorepos | `packages/auth` |
+
+### Semantic Nodes (Developer Knowledge)
+
+| Kind | What It Captures | Example |
+|------|-----------------|---------|
+| **Concept** | Architectural ideas, patterns | "We use the repository pattern for all DB access" |
+| **Decision** | Choices with rationale and alternatives | "Chose Express over Fastify because of middleware ecosystem" |
+| **Bug** | Defects with symptoms and root cause | "Race condition in EventEmitter.on() -- fires before DB ready" |
+| **Solution** | Fixes linked to the bugs they resolve | "Added await to init() -- ensures DB connection before event binding" |
+| **Convention** | Project-specific rules | "All errors must extend AppBaseError" |
+| **Community** | Auto-discovered module clusters | "Authentication subsystem: UserService, JWTProvider, AuthMiddleware" |
+| **ContentChunk** | Indexed documentation sections, execution output | Heading-scoped chunks from ARCHITECTURE.md |
+
+### Event Nodes (Session Timeline)
+
+| Kind | What It Captures | Example |
+|------|-----------------|---------|
+| **SessionNode** | A Claude Code session | Session started at 10:30 AM, 45 events |
+| **EditEvent** | File modifications | Modified `src/auth/jwt.ts` lines 42-58 |
+| **ExecutionEvent** | Command/script runs | `bun run test` -- 3 failures |
+| **ErrorEvent** | Errors encountered | TypeError: Cannot read property 'token' of undefined |
+| **GitEvent** | Git operations | Committed `fix: token refresh` on branch `auth-fix` |
+| **UserDecision** | Developer corrections | "Use Redis instead of Memcached" |
+| **UserPrompt** | Developer messages | Prompt with references to entities |
+| **TaskNode** | Logical task groupings | "Implement JWT refresh token flow" |
+
+---
+
+## MCP Tools (16)
+
+Sia exposes 16 tools via the Model Context Protocol, organized into four categories.
+
+### Memory Tools
+
+#### `sia_search` -- General Memory Retrieval
+
+The primary tool. Called at the start of every non-trivial task.
+
+```
+sia_search({
+  query: "session timeout expiry behavior",
+  task_type: "bug-fix",         // boosts Bug, Solution nodes
+  node_types: ["Decision"],     // narrow by node kind
+  limit: 10,                    // default 5
+  paranoid: true,               // exclude all Tier 4 content
+  workspace: true,              // include cross-repo results
+})
+```
+
+#### `sia_by_file` -- File-Scoped Retrieval
+
+Called before modifying any file. Returns everything Sia knows about that file.
+
+```
+sia_by_file({
+  file_path: "src/services/UserService.ts",
+  workspace: true,
+})
+```
+
+#### `sia_expand` -- Graph Relationship Traversal
+
+Follows edges from a known node. Session budget: 2 calls.
+
+```
+sia_expand({
+  node_id: "...",
+  depth: 2,
+  edge_types: ["supersedes", "caused_by", "solves"],
+})
+```
+
+#### `sia_community` -- Architectural Summaries
+
+Returns module-level descriptions from Leiden community detection.
+
+```
+sia_community({
+  query: "how does the auth module work",
+  level: 1,    // 0=fine, 1=module, 2=architectural overview
+})
+```
+
+#### `sia_at_time` -- Temporal Query
+
+Queries the graph at a historical point. Essential for regression investigation.
+
+```
+sia_at_time({
+  as_of: "30 days ago",
+  node_types: ["Decision", "Solution"],
+  tags: ["caching"],
+})
+```
+
+Returns `nodes[]` (facts valid at that time) and `invalidated_nodes[]` (facts that had ended by then).
+
+#### `sia_note` -- Developer-Authored Knowledge
+
+Create a Tier 1 knowledge node with explicit tags and edges.
+
+```
+sia_note({
+  kind: "Decision",
+  name: "Use Redis for session cache",
+  content: "Chose Redis over Memcached because...",
+  relates_to: ["src/cache/redis.ts"],
+  template: "adr",
+})
+```
+
+#### `sia_flag` -- Mid-Session Capture Signal (opt-in)
+
+Marks an important moment for higher-priority capture. Disabled by default.
+
+```
+sia_flag({ reason: "chose express-rate-limit at route level, not middleware" })
+```
+
+#### `sia_backlinks` -- Incoming Edge Traversal
+
+Returns all nodes that reference a given node, grouped by edge type.
+
+```
+sia_backlinks({
+  node_id: "...",
+  edge_types: ["pertains_to", "caused_by"],
+})
+```
+
+### Sandbox Tools
+
+#### `sia_execute` -- Isolated Subprocess Execution
+
+Run code in an isolated subprocess with stdout capture. Supports 11 runtimes. When output exceeds the context threshold and an intent is provided, Context Mode activates: output is chunked, embedded, indexed, and only relevant chunks returned.
+
+```
+sia_execute({
+  language: "python",
+  code: "import json; print(json.dumps(analyze_logs()))",
+  intent: "find OOM errors",
+})
+```
+
+#### `sia_execute_file` -- File Processing in Sandbox
+
+Like `sia_execute` but mounts a file into the sandbox. Raw content never enters the agent's context.
+
+```
+sia_execute_file({
+  file_path: "logs/production.log",
+  language: "python",
+  code: "parse_and_summarize()",
+})
+```
+
+#### `sia_batch_execute` -- Multi-Command Batch
+
+Execute multiple commands and searches in one call. Creates event nodes with `precedes` edges.
+
+```
+sia_batch_execute({
+  operations: [
+    { type: "execute", language: "bash", code: "git log --oneline -20" },
+    { type: "search", query: "recent authentication changes" },
+    { type: "execute", language: "python", code: "analyze_diff()" },
+  ]
+})
+```
+
+### Graph Management Tools
+
+#### `sia_index` -- Content Indexing
+
+Chunk markdown by headings, create ContentChunk nodes with embeddings.
+
+```
+sia_index({ content: "# API Documentation\n...", source: "api-docs" })
+```
+
+#### `sia_fetch_and_index` -- URL Fetch and Index
+
+Fetch a URL, convert to markdown, chunk and index as Tier 4 ContentChunk nodes.
+
+```
+sia_fetch_and_index({ url: "https://docs.example.com/api" })
+```
+
+#### `sia_ast_query` -- Structural Code Analysis
+
+Run tree-sitter queries against source files.
+
+### Diagnostic Tools
+
+#### `sia_stats` -- Graph Metrics
+
+Returns node counts by kind, edge counts by type, freshness metrics, context savings, native module status.
+
+#### `sia_doctor` -- Health Check
+
+Checks runtimes, hooks, capture mode, LLM provider health, FTS5, sqlite-vss, ONNX model, native module status, graph integrity, and inverted dependency index coverage.
+
+#### `sia_upgrade` -- Self-Update
+
+Fetches latest version, rebuilds, runs migrations, and rebuilds VSS if the schema changed.
+
+#### `sia_sync_status` -- Sync Status
+
+Check team sync configuration and connection status.
+
+### Branch Snapshot Tools
+
+#### `sia_snapshot_list` / `sia_snapshot_restore` / `sia_snapshot_prune`
+
+List, restore, and prune branch snapshots for worktree-aware graph state management.
+
+---
+
+## Skills (46)
+
+Skills are slash commands providing structured workflows. Invoke them in Claude Code with `/sia-<name>`.
+
+### Core
+
+| Skill | Description |
+|---|---|
+| `/sia-learn` | Build complete knowledge graph (install + index + docs + communities) |
+| `/sia-setup` | First-time setup wizard (detect project, configure, learn, tour) |
+| `/sia-install` | Initialize SIA databases and register the repo |
+| `/sia-search` | Guided search with examples |
+| `/sia-stats` | Graph statistics |
+| `/sia-status` | Knowledge graph health dashboard |
+| `/sia-doctor` | System health diagnostics |
+| `/sia-reindex` | Re-parse repository with Tree-sitter |
+| `/sia-playbooks` | Load task-specific playbooks (regression, feature, review, orientation) |
+
+### Knowledge Management
+
+| Skill | Description |
+|---|---|
+| `/sia-capture` | Guided knowledge capture -- decisions, conventions, bugs, solutions |
+| `/sia-execute` | Run code in sandbox with knowledge capture |
+| `/sia-index` | Index external content (text, URLs) |
+| `/sia-workspace` | Manage cross-repo workspaces |
+| `/sia-export-import` | Export/import graphs as portable JSON |
+| `/sia-export-knowledge` | Export graph as human-readable KNOWLEDGE.md |
+| `/sia-history` | Explore temporal knowledge evolution |
+| `/sia-impact` | Analyze impact of planned code changes |
+| `/sia-compare` | Compare graph state between two time points |
+| `/sia-digest` | Daily knowledge summary |
+| `/sia-freshness` | Graph freshness report |
+| `/sia-conflicts` | List and resolve knowledge conflicts |
+| `/sia-prune` | Remove archived entities |
+| `/sia-upgrade` | Self-update SIA |
+
+### Development Workflow
+
+These nine skills augment standard development workflows with graph intelligence:
+
+| Skill | Enhancement Over Standard Workflow |
+|---|---|
+| `/sia-debug-workflow` | Temporal root-cause tracing, known bug lookup, causal chain analysis |
+| `/sia-plan` | Community-aware task decomposition, convention injection per task |
+| `/sia-execute-plan` | Staleness detection, per-task convention checks, session resumption |
+| `/sia-brainstorm` | Surfaces past decisions, rejected alternatives, architectural constraints |
+| `/sia-test` | Known edge cases from Bug history, project test conventions |
+| `/sia-finish` | Semantic PR summaries from graph entities, post-merge knowledge capture |
+| `/sia-dispatch` | Community-based independence verification for parallel agents |
+| `/sia-review-respond` | Past decision context, YAGNI checks via usage patterns |
+| `/sia-verify` | Area-specific requirements, past verification failures, known gotchas |
+
+### Visualization & Onboarding
+
+| Skill | Description |
+|---|---|
+| `/sia-visualize` | Generate static HTML graph visualization |
+| `/sia-visualize-live` | Launch interactive browser-based graph explorer |
+| `/sia-tour` | Interactive guided tour of the knowledge graph |
+
+### Team Sync
+
+| Skill | Description |
+|---|---|
+| `/sia-team` | Join, leave, or check team sync status |
+| `/sia-sync` | Manual push/pull to/from team server |
+
+### Multi-Audience Reporting
+
+| Skill | Audience | What It Produces |
+|---|---|---|
+| `/sia-qa-report` | QA | Changes since last test cycle, risky areas, test priorities |
+| `/sia-qa-coverage` | QA | Test coverage gaps, buggy areas without tests |
+| `/sia-qa-flaky` | QA | Flaky test patterns, recurring failures |
+| `/sia-pm-sprint-summary` | PM | Plain-language progress, decisions, features delivered |
+| `/sia-pm-decision-log` | PM | Chronological decisions with rationale and alternatives |
+| `/sia-pm-risk-dashboard` | PM | Recurring bugs, conflicting decisions, fragile modules |
+| `/sia-lead-drift-report` | Tech Lead | Architecture drift vs captured decisions |
+| `/sia-lead-knowledge-map` | Tech Lead | Knowledge distribution, coverage gaps, bus-factor risks |
+| `/sia-lead-compliance` | Tech Lead | Convention compliance audit across the codebase |
+
+---
+
+## Agents (23)
+
+Agents are specialized subagents dispatched for focused tasks. Invoke via `@sia-<name>` (e.g., `@sia-code-reviewer`). All agents retrieve from the knowledge graph and can run simultaneously.
+
+### Before Coding
+
+| Agent | What It Does |
+|---|---|
+| `sia-orientation` | Answers specific architecture questions from the graph |
+| `sia-onboarding` | Comprehensive multi-topic onboarding session |
+| `sia-decision-reviewer` | Surfaces past decisions and rejected alternatives |
+| `sia-explain` | Explains SIA's graph structure, tools, and capabilities |
+
+### During Coding
+
+| Agent | What It Does |
+|---|---|
+| `sia-feature` | Feature development with convention awareness and dependency context |
+| `sia-refactor` | Impact analysis via dependency graph before structural changes |
+| `sia-migration` | Plans knowledge graph updates during major refactoring |
+| `sia-convention-enforcer` | Checks code against all known conventions |
+| `sia-dependency-tracker` | Cross-repo dependency monitoring and API contract tracking |
+| `sia-security-audit` | Security review with paranoid mode and Tier 4 exposure tracking |
+| `sia-test-advisor` | Test strategy from past failures, coverage gaps, and edge cases |
+
+### Debugging
+
+| Agent | What It Does |
+|---|---|
+| `sia-debug` | Temporal root-cause investigation using `sia_at_time` and causal history |
+| `sia-regression` | Regression risk analysis from known bugs and failure patterns |
+
+### Code Review
+
+| Agent | What It Does |
+|---|---|
+| `sia-code-reviewer` | Reviews with historical context, convention enforcement, regression detection |
+| `sia-conflict-resolver` | Resolves contradicting knowledge entities with evidence |
+
+### After Coding
+
+| Agent | What It Does |
+|---|---|
+| `sia-knowledge-capture` | Systematic review and capture of uncaptured session knowledge |
+| `sia-changelog-writer` | Generates changelogs from decisions, bugs fixed, and features added |
+
+### QA, PM & Tech Lead
+
+| Agent | What It Does |
+|---|---|
+| `sia-qa-analyst` | Regression risks, coverage gaps, test recommendations |
+| `sia-qa-regression-map` | Scored regression risk map (0-100) per module |
+| `sia-pm-briefing` | Plain-language project briefings for PMs |
+| `sia-pm-risk-advisor` | Technical risk in business-impact language |
+| `sia-lead-architecture-advisor` | Architecture drift detection against captured decisions |
+| `sia-lead-team-health` | Knowledge distribution, coverage gaps, capture rate trends |
+
+---
+
+## Knowledge Graph Features
+
+### Bi-Temporal Model
+
+Every fact (nodes and edges) carries four timestamps:
+
+- **`t_created`** -- when Sia recorded the fact
+- **`t_expired`** -- when Sia marked it superseded
+- **`t_valid_from`** -- when the fact became true in the world
+- **`t_valid_until`** -- when it stopped being true (null = still true)
+
+Facts are never deleted -- only invalidated. This enables temporal queries like "what was the authentication strategy in January?" via `sia_at_time`.
+
+### Branch-Aware Snapshots
+
+When you switch branches, the PostToolUse hook saves a snapshot of the current graph state tagged with the departing branch, then restores the arriving branch's snapshot. Each git worktree gets its own graph database instance. The `/sia-finish` skill handles snapshot pruning after merge.
+
+### Community Detection
+
+Leiden clustering at three resolution levels groups related code into communities. Communities are summarized (LLM-based when available, plain-text fallback) and queryable via `sia_community`.
+
+### Ontology Enforcement
+
+Every edge is validated against a declarative `edge_constraints` table. Invalid relationships are rejected at the SQLite trigger level. Additional constraints: Bug nodes must have `caused_by` edges, Convention nodes must have `pertains_to` edges, `supersedes` edges can only connect same-kind nodes.
+
+### Five-Layer Freshness Engine
+
+```
+Layer 1 -- File-Watcher Invalidation     [milliseconds]   [>90% of cases]
+  File save --> Tree-sitter incremental re-parse --> surgical node invalidation
+Layer 2 -- Git-Commit Reconciliation      [seconds]        [merges, rebases, checkouts]
+  Git operation --> diff parse --> bounded BFS with firewall nodes
+Layer 3 -- Stale-While-Revalidate Reads   [per-query]      [~0.1ms overhead]
+  Fresh --> serve instantly | Stale --> serve + async re-validate | Rotten --> block + repair
+Layer 4 -- Confidence Decay               [hours to days]  [LLM-inferred facts only]
+  Exponential decay x trust tier, with Bayesian re-observation reinforcement
+Layer 5 -- Periodic Deep Validation       [daily/weekly]   [batch cleanup]
+  Doc-vs-code cross-check --> LLM re-verify --> PageRank recompute --> compaction
+```
+
+Each search result carries a `freshness` field (`fresh`, `stale`, or `rotten`) so the agent knows whether to cite with confidence or verify first.
+
+---
+
+## Performance
+
+### Worker-Threaded Indexer
+
+- **Worker thread pool** -- configurable (default: CPU count - 1), each worker parses independently via Tree-sitter
+- **Batch SQL** -- 100 insertions per transaction
+- **Periodic cache saves** -- every 500 files; crashes lose at most one interval's work
+- **Per-file retry** -- individual parse failures logged without stopping the overall index
+- **Incremental mode** -- skips files with unchanged mtime
+
+### Expected Performance
+
+| Operation | Target |
+|-----------|--------|
+| Hybrid search (50K nodes) | <800ms |
+| Incremental AST re-parse | <200ms per file |
+| Full capture pipeline | <8s after hook fires |
+| Workspace search (2 x 25K nodes) | <1.2s |
+| Community detection (10K nodes) | <30s |
+| File-save invalidation (end-to-end) | <200ms |
+| Sandbox execution (simple script) | <5s |
+| Graph visualization (100 nodes) | <3s render |
+
+### Crash Recovery
+
+If `/sia-learn` crashes mid-run (OOM, Ctrl+C, power loss), re-running automatically resumes from the last checkpoint. A `.sia-learn-progress.json` file tracks progress per phase and is deleted on successful completion.
+
+---
+
+## Multi-Audience Intelligence
+
+SIA generates role-specific reports from the same knowledge graph.
+
+**QA teams** get regression risk maps with numeric scores (0-100) per module combining bug density, change velocity, and dependency fan-out. Coverage gap analysis surfaces buggy areas without tests. Flaky test tracking identifies intermittent failures.
+
+**Project managers** get plain-language sprint summaries (decisions made, bugs fixed, features delivered), chronological decision logs with rationale and alternatives, and risk dashboards scoring technical risk in business-impact language.
+
+**Tech leads** get architecture drift reports comparing current code against captured decisions, knowledge distribution maps showing bus-factor risks, and convention compliance audits checking every known convention against current code.
+
+---
+
+## Visualization
+
+Browser-based interactive graph explorer with four views:
+
+| View | What It Shows |
+|---|---|
+| **Graph Explorer** | Force-directed graph -- click to expand, filter by type/tier, zoom and pan |
+| **Timeline** | Temporal history -- when decisions were made, bugs found, entities invalidated |
+| **Dependency Map** | File dependency map -- imports, calls, depends_on edges |
+| **Community Clusters** | Leiden-detected module groups with summaries and inter-cluster edges |
+
+```bash
+/sia-visualize-live                    # Graph explorer (default)
+/sia-visualize-live --view timeline    # Temporal timeline
+/sia-visualize-live --view deps        # Dependency map
+/sia-visualize-live --view communities # Community clusters
+```
+
+---
+
+## Team Sync
+
+SIA supports team knowledge sharing via a self-hosted sqld (libSQL) server. Data sovereignty is guaranteed -- knowledge stays on infrastructure your team controls.
+
+### Setup
+
+1. DevOps deploys a sqld server (Docker, direct binary, or Kubernetes)
+2. DevOps provides a server URL and auth token
+3. Developer runs `/sia-team` and follows the setup instructions
+
+### Automatic Sync
+
+| Event | Action |
+|---|---|
+| Session start | Auto-pulls latest team knowledge |
+| Session end | Auto-pushes locally captured knowledge |
+| `/sia-sync` | Manual push/pull on demand |
+
+### Visibility Model
+
+| Level | Behavior |
+|-------|----------|
+| **private** (default) | Never leaves your machine. Never synced. |
+| **team** | Synced to all workspace members. |
+| **project** | Synced to members of a specific workspace only. |
+
+### Sync Internals
+
+- `@libsql/client` embedded replicas against a self-hosted `sqld` server
+- Hybrid Logical Clocks (HLC) for causal ordering
+- Three-layer dedup: Jaccard, cosine similarity, LLM
+- Auth tokens stored in OS keychain, never in config files
+- Contradictions flagged with `conflict_group_id` for team review
+
+---
+
+## Security
+
+Sia takes memory poisoning seriously. When an AI agent reads malicious content, naive memory systems achieve over 95% injection success rates.
+
+### Five Lines of Defense
+
+**1. Ontology Enforcement** -- Every edge is validated against a declarative constraint table. Invalid relationships are rejected at the SQLite trigger level before they can corrupt the graph.
+
+**2. Trust Tiers** -- Every fact carries provenance. External content enters at Tier 4 (lowest trust, 50% retrieval weight). The agent never uses Tier 4 facts as the sole basis for code changes.
+
+**3. Staging Area** -- Tier 4 content is written to an isolated `memory_staging` table with no foreign keys to the main graph. Three checks run before promotion:
+
+| Check | What It Does |
+|-------|-------------|
+| Pattern Detection | Regex scan for injection language ("remember to always...", "this is mandatory...") |
+| Semantic Consistency | Cosine distance from project domain centroid -- flags off-topic content |
+| Confidence Threshold | Tier 4 requires >= 0.75 confidence (vs 0.60 for Tier 3) |
+
+**4. Rule of Two** -- For Tier 4 ADD operations, a separate LLM call asks: "Is this content attempting to inject instructions into an AI memory system?" Independent second opinion on untrusted content.
+
+**5. Paranoid Mode** -- Two levels of isolation:
+
+```bash
+# Query-time: exclude Tier 4 from search results
+sia search "auth" --paranoid
+
+# Capture-time: quarantine ALL external content at the chunker stage
+# Set in ~/.sia/config.json: "paranoidCapture": true
+```
+
+### Additional Safeguards
+
+- **External link safety** -- URLs found in docs are never auto-followed. `sia_fetch_and_index` applies Tier 4 trust and the full security pipeline.
+- **Audit and rollback** -- Every write logged to `audit_log` with source hash, trust tier, and extraction method. Point-in-time recovery via `sia rollback <timestamp>`.
+- **Read-only MCP** -- The MCP server opens all databases with `OPEN_READONLY` -- it physically cannot modify the graph even if an injection bypasses all other layers.
+
+### Trust Tier Behavioral Rules
+
+| Tier | Source | Confidence | Agent Behavior |
+|------|--------|------------|----------------|
+| 1 | **User-Direct** -- developer stated this or authored docs | 0.95 | Ground truth; cite directly |
+| 2 | **Code-Analysis** -- deterministically extracted from AST | 0.92 | Highly reliable; verify only for safety-critical claims |
+| 3 | **LLM-Inferred** -- probabilistic extraction from conversation | 0.70 | Qualify: "Sia suggests X -- let me verify" |
+| 4 | **External** -- from fetched URLs or unknown sources | 0.50 | Reference only; never sole basis for code changes |
+
+---
+
+## Language Support
+
+### Supported Languages
+
+| Tier | Capability | Languages |
+|------|-----------|-----------|
+| **A** -- Full extraction | Functions, classes, imports, call sites | TypeScript, TSX, JavaScript, JSX, Python, Go, Rust, Java, Kotlin, Swift, PHP, Ruby, Scala, Elixir, Dart |
+| **B** -- Structural | Functions, classes, imports (no call tracking) | C, C++, C#, Bash/Shell, Lua, Zig, Perl, R, OCaml, Haskell |
+| **C** -- Schema | Custom extractors for data definitions | SQL (tables, columns, FKs, indexes), Prisma schema |
+| **D** -- Manifest | Dependency edges from project files | `Cargo.toml`, `go.mod`, `pyproject.toml`, `.csproj`/`.sln`, `build.gradle`/`pom.xml` |
+
+### Sandbox Execution Runtimes
+
+`sia_execute` supports 11 runtimes: Python, Node.js, Bun, Bash, Ruby, Go, Rust, Java, PHP, Perl, and R.
+
+### Native Performance Module (Optional)
+
+Optional Rust module (`@sia/native`) distributed as prebuilt binaries. No Rust toolchain required.
+
+| Operation | Rust Native | Wasm | TypeScript |
+|-----------|------------|------|------------|
+| AST diff (500-node trees) | < 10ms | < 25ms | < 100ms |
+| PageRank (50K nodes) | < 20ms | < 50ms | < 80ms |
+| Leiden (50K nodes, 3 levels) | < 500ms | < 500ms | < 1s (Louvain) |
+
+Graceful three-tier fallback: Rust native --> Wasm --> pure TypeScript. All tiers produce identical results.
+
+### Adding Languages
+
+Register additional Tree-sitter grammars at runtime:
+
+```json
+// ~/.sia/config.json
+{
+  "additionalLanguages": [
+    { "name": "gleam", "extensions": [".gleam"], "grammar": "tree-sitter-gleam", "tier": "B" }
+  ]
+}
+```
+
+---
+
+## CLI Reference
+
+### Core Commands
+
+```bash
+sia install                     # Install and index the repository
+sia stats                       # Graph statistics
+sia search <query>              # Search the knowledge graph
+sia search --paranoid <query>   # Exclude all Tier 4 content
+sia reindex                     # Re-parse AST backbone and re-discover docs
+sia doctor                      # Health check (runtimes, hooks, model, graph integrity)
+sia doctor --providers          # LLM provider connectivity and cost estimate
+sia upgrade                     # Self-update with migration
+sia freshness                   # Graph freshness report
+sia prune                       # Clean up decayed entities
+sia rollback <timestamp>        # Restore graph to a previous state
+```
+
+### Knowledge Commands
+
+```bash
+sia learn                       # Build complete knowledge graph
+sia learn --incremental         # Update changed files only
+sia learn --force               # Full rebuild ignoring caches
+sia community                   # View community summaries
+sia digest --period 7d          # Weekly knowledge digest
+sia download-model              # Download/update the ONNX embedding model
+sia enable-flagging             # Enable sia_flag mid-session capture
+sia disable-flagging
+```
+
+### Visualization
+
+```bash
+sia graph --open                # Interactive graph in browser
+sia graph --scope src/auth/     # Visualize a subgraph
+```
+
+### Export/Import
+
+```bash
+sia export                      # Export graph for backup or migration
+sia export --format markdown    # Obsidian-compatible markdown vault
+sia import                      # Import a previously exported graph
+sia import --format markdown <dir>
+sia export-knowledge            # Generate KNOWLEDGE.md
+```
+
+### Workspace Commands
+
+```bash
+sia workspace create "My App" --repos ./frontend ./backend
+sia workspace list
+sia workspace show "My App"
+sia workspace add "My App" ./shared-lib
+sia workspace remove "My App" ./old-service
+```
+
+### Team Commands
+
+```bash
+sia team join <url> <token>     # Join a team
+sia team leave
+sia team status
+sia sync push                   # Push knowledge to team
+sia sync pull                   # Pull from team
+sia share <node-id>             # Promote node to team visibility
+sia conflicts list              # View unresolved contradictions
+sia conflicts resolve           # Resolve a contradiction
+```
+
+### Multi-Audience Reports
+
+```bash
+sia qa-report                   # QA-focused report
+sia pm-report                   # PM sprint summary / decision log / risk dashboard
+sia lead-report                 # Architecture drift / knowledge map / compliance
+```
+
+### Standalone Alternative
+
+All `sia` commands can also be run as `npx sia <command>` when not using plugin mode.
+
+---
+
+## Configuration
+
+All configuration lives in `~/.sia/config.json` (created by `sia install`).
+
+### Key Settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `captureModel` | `claude-haiku-4-5-20251001` | LLM for extraction, consolidation, security checks |
+| `minExtractConfidence` | `0.6` | Minimum confidence for LLM-extracted candidates |
+| `paranoidCapture` | `false` | Quarantine all Tier 4 content at chunker stage |
+| `enableFlagging` | `false` | Enable `sia_flag` for mid-session capture |
+| `airGapped` | `false` | Disable all outbound network calls (LLM) |
+| `maxResponseTokens` | `1500` | Max tokens per MCP tool response |
+| `workingMemoryTokenBudget` | `8000` | Token budget before working memory compaction |
+| `communityTriggerNodeCount` | `20` | New nodes before community re-detection |
+| `communityMinGraphSize` | `100` | Minimum graph size for Leiden |
+| `archiveThreshold` | `0.05` | Importance below which decayed nodes are archived |
+| `sandboxTimeout` | `30000` | Subprocess execution timeout (ms) |
+| `contextModeThreshold` | `5000` | Output bytes before Context Mode activates |
+
+### LLM Provider Configuration
+
+Capture mode and LLM providers are configured in `sia.config.yaml`:
+
+```yaml
+capture:
+  mode: hooks              # hooks | api | hybrid
+
+providers:
+  summarize:
+    provider: anthropic
+    model: claude-sonnet-4
+  validate:
+    provider: ollama
+    model: qwen2.5-coder:7b
+  extract:                 # active in api/hybrid only
+    provider: anthropic
+    model: claude-haiku-4-5
+  consolidate:             # active in api/hybrid only
+    provider: anthropic
+    model: claude-haiku-4-5
+
+fallback:
+  chain: [anthropic, openai, ollama]
+  maxRetries: 3
+
+costTracking:
+  budgetPerDay: 1.00
+```
+
+### Air-Gapped Mode
+
+Set `"airGapped": true` for zero outbound network calls. This disables LLM extraction, consolidation, community summaries, and the Rule of Two security check. ONNX embeddings, vector search, BM25, graph traversal, hooks, sandbox execution, and doc ingestion remain fully functional.
+
+---
+
+## Multi-Repo Workspaces
+
+### Single Repository (default)
+
+Each repo gets an isolated SQLite database at `~/.sia/repos/<hash>/graph.db`.
+
+### Workspace (linked repos)
+
+```bash
+sia workspace create "Acme Fullstack" --repos ./frontend ./backend
+```
+
+Cross-repo relationships are auto-detected from: OpenAPI/Swagger specs, GraphQL schemas, TypeScript project references, `.csproj` references, `Cargo.toml` workspace members, `go.mod` replace directives, `pyproject.toml` path dependencies, and `workspace:*` npm dependencies.
+
+### Monorepo
+
+Auto-detected from `pnpm-workspace.yaml`, `package.json` workspaces, `nx.json`, or Gradle multi-project builds. All packages share one `graph.db` scoped by `package_path`.
+
+---
+
+## Onboarding & Export
+
+**`/sia-setup`** -- First-time wizard: detects project type and languages, creates databases, runs `/sia-learn`, launches `/sia-tour`.
+
+**`/sia-tour`** -- Interactive guided tour covering architecture, decisions, conventions, and known issues.
+
+**`/sia-export-knowledge`** -- Exports the graph as a human-readable `KNOWLEDGE.md` for team onboarding, sharing outside SIA, or generating project documentation.
+
+---
+
+## v2 Roadmap
+
+- Natural language graph queries ("what changed in auth last week?")
+- PR review integration with graph-backed suggestions
+- External source ingestion (Slack, Notion, Jira, Confluence)
+- PM tool sync (bidirectional Jira/Linear integration)
+- Graph analytics dashboard (trend lines, health scores)
+- Embedding model upgrade (domain-tuned code embeddings)
+- Lifecycle notifications (Slack/Teams alerts for drift, risk, compliance)
+
+---
+
+## Compatibility
+
+- **OS**: macOS, Linux, Windows (WSL2)
+- **Runtime**: Node.js 18+, Bun 1.0+
+- **Transport**: Standard MCP stdio
+- **AI Agent**: Claude Code (native hooks), Cursor (hook adapter), Cline (hook adapter), Windsurf/Aider (MCP-only), any MCP-compatible agent
+- **LLM Providers**: Anthropic, OpenAI, Google, Ollama via Vercel AI SDK
+- **Native module**: Prebuilt for macOS (ARM/Intel), Linux (x64/ARM64, glibc/musl), Windows (x64)
+
+---
+
+## Storage
+
+```
+~/.sia/
+  meta.db                               # workspace/repo registry, sharing rules
+  bridge.db                             # cross-repo edges
+  config.json                           # user configuration
+  repos/<sha256-of-repo-path>/
+    graph.db                            # unified graph (nodes, edges, communities, ontology)
+    episodic.db                         # append-only interaction archive
+  models/
+    all-MiniLM-L6-v2.onnx              # local embedding model (~90MB)
+  ast-cache/<hash>/                     # Tree-sitter parse cache
+  snapshots/<hash>/YYYY-MM-DD.snapshot  # daily graph snapshots
+  logs/sia.log                          # structured JSON log
+```
+
+---
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE) for details.
+
+Attribution is required for all distributions, including commercial use.