@rkarim08/sia 1.0.0

package/skills/sia-search/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: sia-search
+description: Searches SIA's knowledge graph for project knowledge — decisions, conventions, bugs, patterns, and architecture. Use when looking up past decisions, finding conventions, or querying project history.
+---
+
+# SIA Search
+
+Search the project's persistent knowledge graph for relevant information.
+
+## When To Use
+
+Use this skill when you need to:
+- Understand project conventions or past decisions
+- Find known bugs or solutions
+- Look up architecture patterns
+- Get context about a specific file or module
+- Recall what was discussed in previous sessions
+
+## How To Search
+
+Use the `sia_search` MCP tool directly. It supports these parameters:
+
+- **query** (required): Natural language search query
+- **task_type** (optional): One of `orientation`, `feature`, `bug-fix`, `regression`, `review` — helps tune result ranking
+- **node_types** (optional): Filter to specific types like `["Decision", "Convention", "Bug"]`
+- **package_path** (optional): Scope search to a specific package/module
+- **workspace** (optional): Search across all repos in the workspace, not just the current one
+- **paranoid** (optional): Enable extra validation on results
+- **include_provenance** (optional): Include source provenance metadata in results
+- **limit** (optional): Max results (default varies by query type)
+
+### Examples
+
+```
+sia_search({ query: "authentication flow", task_type: "feature" })
+sia_search({ query: "known bugs in payment module", node_types: ["Bug", "Solution"] })
+sia_search({ query: "coding conventions", node_types: ["Convention"], limit: 20 })
+```
+
+## Related Tools
+
+- `sia_by_file` — Look up knowledge for a specific file path
+- `sia_expand` — Explore the neighborhood of a specific entity
+- `sia_community` — Get high-level summaries by community/module
+- `sia_at_time` — Query the graph at a historical point in time
+- `sia_backlinks` — Find all entities that reference a given entity
+- `sia_note` — Record a new Decision, Convention, Bug, Solution, or Concept

package/skills/sia-setup/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: sia-setup
+description: Guides first-time SIA setup — detects the project, configures the knowledge graph, indexes code and docs, and runs a tour. Use when setting up SIA for the first time in a new project.
+---
+
+# SIA First-Time Setup
+
+Welcome to SIA! This wizard gets you set up in one step.
+
+**For detailed phase guide with error recovery:** See [setup-checklist.md](setup-checklist.md)
+
+## What This Does
+
+1. Detects your project type, languages, and structure
+2. Creates SIA databases and registers the repository
+3. Indexes all source code with tree-sitter (25+ languages)
+4. Ingests project documentation (README, ARCHITECTURE, ADRs, etc.)
+5. Detects community structure (module clusters)
+6. Gives you a tour of what was discovered
+
+## Setup Process
+
+### Step 1: Detect Project
+
+First, let's understand your project:
+
+```bash
+# Detect project type
+ls package.json Cargo.toml go.mod pyproject.toml requirements.txt Gemfile 2>/dev/null
+# Count source files
+find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" \) -not -path "*/node_modules/*" -not -path "*/.git/*" | wc -l
+# Check for existing docs
+ls README.md ARCHITECTURE.md CLAUDE.md AGENTS.md docs/ 2>/dev/null
+```
+
+Present findings to the user:
+> "I detected a TypeScript project with 342 source files, a README.md, and docs/ directory. Ready to set up SIA?"
+
+### Step 2: Configure (optional questions)
+
+Ask only if relevant:
+- **Team sync:** "Will multiple developers use SIA on this project? If yes, I'll set up team sync later via `/sia-team`."
+- **Large repo warning:** If >5,000 files: "This is a large repo. The first index may take a few minutes. Want to proceed?"
+
+### Step 3: Run Learn
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts learn --verbose
+```
+
+This handles install + index + doc ingestion + community detection automatically.
+
+### Step 4: Tour
+
+After learning completes, run the tour:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts tour
+```
+
+Or invoke `/sia-tour` for an interactive walkthrough.
+
+### Step 5: Summary
+
+Present what SIA learned:
+> **SIA is ready!**
+> - 342 code entities indexed across 142 files
+> - 45 documentation chunks from 8 docs
+> - 5 community clusters detected
+> - 3 external references (Notion, Jira, GitHub)
+>
+> Try these next:
+> - Ask me any question — SIA tools activate automatically
+> - `/sia-search` — search the knowledge graph
+> - `/sia-status` — check graph health
+> - `/sia-team` — set up team sync
+
+## When To Use
+
+- First time using SIA on a project
+- After cloning a project that already has a SIA graph
+- When you want a fresh start (`/sia-learn --force` then `/sia-setup`)

package/skills/sia-setup/setup-checklist.md

@@ -0,0 +1,97 @@
+# SIA Setup — Detailed Phase Guide
+
+Progressive disclosure for the setup wizard. SKILL.md has the overview; this file has the details and error recovery for each phase.
+
+## Phase 1: Project Detection
+
+**What happens:** Detect project type, package manager, test runner, framework.
+
+**Checks:**
+- `package.json` → Node.js project (bun/npm/yarn/pnpm)
+- `Cargo.toml` → Rust project
+- `go.mod` → Go project
+- `pyproject.toml` / `setup.py` → Python project
+- `.git` → Git repository (required)
+
+**Error recovery:**
+| Error | Fix |
+|---|---|
+| No `.git` directory | Run `git init` first — SIA needs git for temporal tracking |
+| No package manifest | SIA can still work — tree-sitter indexes raw source files |
+| Multiple manifests | Ask user which is primary; index all |
+
+## Phase 2: Database Configuration
+
+**What happens:** Create SQLite databases for entities, edges, embeddings.
+
+**Checks:**
+- Write permission to `.sia/` directory
+- SQLite available (bundled with bun/node)
+- Sufficient disk space (estimate: ~1MB per 1000 entities)
+
+**Error recovery:**
+| Error | Fix |
+|---|---|
+| Permission denied | Check `.sia/` directory ownership; suggest `chmod` |
+| Disk full | Warn user; suggest pruning old data or different location |
+| Existing databases | Ask: fresh install or upgrade? Don't overwrite without consent |
+
+## Phase 3: Code Indexing
+
+**What happens:** Run tree-sitter AST parser on all source files.
+
+**Checks:**
+- Tree-sitter grammars available for detected languages
+- File count and estimated indexing time
+- Ignore patterns (node_modules, dist, build, .git)
+
+**Error recovery:**
+| Error | Fix |
+|---|---|
+| No grammar for language | Warn and skip — SIA works without AST, just less richly |
+| Timeout on large repos | Suggest indexing a subdirectory first; `--include` flag |
+| Parse errors on specific files | Log and continue — partial index is better than none |
+
+## Phase 4: Documentation Ingestion
+
+**What happens:** Ingest markdown docs, README, CLAUDE.md as Tier 4 entities.
+
+**Checks:**
+- Find all `.md` files in repo root and docs/
+- Skip node_modules, vendor, generated docs
+- Chunk large documents (>2000 tokens per chunk)
+
+**Error recovery:**
+| Error | Fix |
+|---|---|
+| No markdown files | Skip — not required |
+| Very large docs (>50 files) | Index incrementally; show progress |
+
+## Phase 5: Community Detection
+
+**What happens:** Run Louvain community detection on the entity graph.
+
+**Checks:**
+- Minimum 10 entities required for meaningful communities
+- Graph must have edges (code entities need imports/calls relationships)
+
+**Error recovery:**
+| Error | Fix |
+|---|---|
+| Too few entities | Skip community detection; re-run after more sessions |
+| No edges | AST indexing may have failed; re-run `sia-reindex` |
+| Single giant community | Normal for small projects; communities emerge as graph grows |
+
+## Phase 6: Verification
+
+**What happens:** Verify the setup is complete and show results.
+
+**Success criteria:**
+- [ ] Databases exist and are readable
+- [ ] Entity count > 0
+- [ ] At least one community detected (or explained why not)
+- [ ] `sia_search` returns results for a basic query
+
+**Present to user:**
+> "SIA is ready. Your project has {N} entities across {M} communities.
+> Try `sia search <topic>` to query the graph, or run `/sia-tour` for a guided walkthrough."

package/skills/sia-stats/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: sia-stats
+description: Shows SIA knowledge graph statistics — entity counts, edges, communities, and database sizes. Use when checking graph health, monitoring growth, or diagnosing capacity issues.
+---
+
+# SIA Stats
+
+Display statistics about the project's knowledge graph.
+
+## Steps
+
+Run the stats command:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/stats.ts
+```
+
+Or use the `sia_stats` MCP tool directly:
+
+```
+sia_stats({})
+sia_stats({ include_session: true })
+```
+
+Parameters:
+- **include_session** (optional): Include stats for the current session (entities created, flags raised)
+
+## Output
+
+This shows:
+- Total entities by type (CodeSymbol, Decision, Convention, Bug, etc.)
+- Total edges by type
+- Community count and hierarchy depth
+- Database file sizes
+- Last index timestamp
+- Session count

package/skills/sia-status/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: sia-status
+description: Shows SIA knowledge graph health — entity counts by type and tier, conflicts, and capture rate. Use for quick health checks, monitoring, or when the user asks about SIA status.
+---
+
+# SIA Status
+
+Display a health dashboard for the project's knowledge graph.
+
+## Steps
+
+Run the status command:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/status.ts
+```
+
+Or via the CLI:
+
+```bash
+sia status
+```
+
+## Output
+
+The dashboard shows:
+
+- **Total entities** — active (non-archived, non-invalidated) entity count
+- **Total edges** — active relationship count
+- **Communities** — detected community count
+- **Conflicts** — number of unresolved conflict groups
+- **Archived** — entities removed from active graph
+- **Recent (24h)** — entities created in the last 24 hours (capture rate indicator)
+- **Graph age** — days between oldest and newest entity
+
+### By Type
+Breakdown of entities by type (CodeEntity, Decision, Convention, Bug, Solution, etc.), sorted by count descending.
+
+### By Trust Tier
+Breakdown by trust tier:
+- **Tier 1 (User-Direct)** — developer-stated facts
+- **Tier 2 (Code-Analysis)** — deterministic AST/regex extraction
+- **Tier 3 (LLM-Inferred)** — AI-generated hypotheses
+- **Tier 4 (External)** — external references

package/skills/sia-sync/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: sia-sync
+description: Pushes or pulls SIA knowledge to/from the team sync server. Use when sharing knowledge with teammates, syncing after a long offline period, or receiving others' captured knowledge.
+---
+
+# SIA Manual Sync
+
+Manually trigger a push or pull of knowledge to/from the team sync server.
+
+Sync normally happens automatically (pull on session start, push on session end). Use this skill when you want to sync mid-session — for example, when you know a teammate just finished capturing important decisions.
+
+## Push Local Knowledge
+
+Push your locally captured knowledge to the team:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts sync push
+```
+
+## Pull Team Knowledge
+
+Pull knowledge from teammates:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts sync pull
+```
+
+## Push and Pull
+
+Do both (push first, then pull):
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts sync
+```
+
+## Output
+
+The command reports what was synced:
+```
+Push: 5 entities, 12 edges, 0 bridge edges
+Pull: 3 entities, 8 edges, 2 VSS refreshed
+```
+
+## Prerequisites
+
+Team sync must be configured first. Run `/sia-team` to set up.

package/skills/sia-team/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: sia-team
+description: Manages SIA team sync — joining servers, checking status, or leaving teams. Use when setting up team knowledge sharing, checking sync health, or managing team membership.
+---
+
+# SIA Team Sync Management
+
+Manage team-based knowledge graph synchronization. SIA syncs knowledge between team members via a self-hosted sqld (libSQL) server managed by your DevOps team.
+
+## Prerequisites
+
+Your DevOps team must have deployed a sqld sync server. You need:
+1. The server URL (e.g., `http://sync.internal:8080` or `https://sia-sync.yourcompany.com`)
+2. An auth token (JWT, provided by DevOps)
+
+## Join a Team
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts team join <server-url> <auth-token>
+```
+
+This will:
+1. Store the auth token securely in the OS keychain
+2. Configure sync with the provided server URL
+3. Generate a unique developer ID for this machine
+
+After joining, run `/sia-sync` to pull existing team knowledge, then sync is **automatic**:
+- **Session start:** Pulls latest team knowledge
+- **Session end:** Pushes your captured knowledge
+
+## Check Status
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts team status
+```
+
+Or use the `sia_sync_status` MCP tool for programmatic access.
+
+## Leave a Team
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts team leave
+```
+
+Disables sync and removes the auth token. Local knowledge is preserved.
+
+## How Sync Works
+
+| Event | What Happens |
+|---|---|
+| Session start | Auto-pulls latest team knowledge via libSQL replication |
+| Session end | Auto-pushes locally captured knowledge |
+| `/sia-sync` | Manual push/pull on demand |
+
+- **Ordering:** Hybrid Logical Clock (HLC) ensures causal consistency
+- **Dedup:** 3-layer deduplication (name Jaccard, embedding cosine, optional LLM)
+- **Conflicts:** Detected via embedding similarity, flagged for resolution
+- **Privacy:** Only non-private entities are synced
+
+## Troubleshooting
+
+- **"Token not found":** Re-run join with your auth token
+- **"Server unreachable":** Check network connectivity to the sync server URL
+- **"Sync not configured":** Run join first

package/skills/sia-test/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: sia-test
+description: Guides test-driven development using SIA's knowledge of test conventions, known edge cases, and past failures. Use when implementing features or fixes with TDD, writing tests, or establishing test patterns.
+---
+
+## Invariants
+
+> These rules have NO exceptions. Violating any one means starting over.
+>
+> 1. YOU MUST query SIA before writing the first test. A test written without
+>    querying SIA may miss known edge cases and WILL be deleted and rewritten.
+> 2. Every Bug entity returned by SIA for the area MUST have a corresponding
+>    regression test. No exceptions.
+> 3. Tests MUST follow the conventions discovered in the graph. "I prefer a
+>    different style" is not a valid reason to deviate.
+
+## Red Flags — If You Think Any of These, STOP
+
+| Thought | Why It's Wrong |
+|---------|---------------|
+| "This is too simple for a SIA query" | Simple-looking areas are where regressions hide. The query takes 2 seconds; missing a known bug costs hours. |
+| "I already know the test conventions" | The graph may contain conventions from sessions you weren't part of. Check. |
+| "I'll query SIA after writing the tests" | By then you've already locked in assumptions. Query FIRST. |
+| "There probably aren't any known bugs here" | You don't know what you don't know. That's why the graph exists. |
+| "The test file already has patterns I can follow" | File patterns may be outdated. SIA knows the current conventions. |
+
+# SIA-Enhanced Test-Driven Development
+
+TDD informed by SIA's knowledge graph — surfaces this project's test conventions, known edge cases from past bugs, and actual interface contracts before writing the first test.
+
+## Checklist
+
+```
+- [ ] Before RED: YOU MUST query SIA for test conventions, known bugs, and file entities. Without this, you will miss edge cases. No exceptions.
+- [ ] RED: Write failing test following discovered conventions + known edge cases. Every Bug entity MUST have a regression test.
+- [ ] GREEN: Minimal code to pass (YAGNI — do NOT over-implement)
+- [ ] REFACTOR: YOU MUST query sia_expand before refactoring to verify no consumers break
+- [ ] Capture: Note new edge cases or test conventions to graph. A test session that discovers patterns but doesn't capture them is incomplete.
+```
+
+## Red-Green-Refactor
+
+### Before RED — SIA Context Query (NEW)
+
+Before writing the first test:
+
+```
+sia_search({ query: "test conventions patterns <area>", node_types: ["Convention"], limit: 10 })
+sia_search({ query: "bugs failures edge cases <area>", node_types: ["Bug"], limit: 10 })
+sia_by_file({ file_path: "<source_file_being_tested>" })
+```
+
+From the results:
+- **Test conventions** → follow the same patterns (setup/teardown style, assertion library, naming)
+- **Known bugs** → write tests that cover these edge cases
+- **File entities** → understand the actual API surface to test against
+
+**For common anti-patterns to avoid:** See [testing-anti-patterns.md](testing-anti-patterns.md)
+
+### RED — Write Failing Test (enhanced)
+
+Write the test following discovered conventions. Include edge cases from known Bug history.
+
+### GREEN — Write Minimal Code (same as standard)
+
+YAGNI — write the simplest code to pass.
+
+### REFACTOR — Clean Up (enhanced)
+
+```
+sia_expand({ entity_id: "<entity_under_test>", depth: 1, edge_types: ["calls", "imports"] })
+```
+
+Check what depends on the code being refactored. Ensure refactoring doesn't break consumers.
+
+### After Cycle — Capture (NEW)
+
+If a test revealed a new edge case or bug:
+
+```
+sia_note({ kind: "Bug", name: "<edge case found>", content: "<description>" })
+```
+
+If a new test convention was established:
+
+```
+sia_note({ kind: "Convention", name: "<test pattern>", content: "<how we test this type of thing>" })
+```
+
+## Key Principle
+
+**Tests should match the codebase's style, not a generic template.** SIA knows how THIS project writes tests — follow that pattern.

package/skills/sia-test/testing-anti-patterns.md

@@ -0,0 +1,104 @@
+# Testing Anti-Patterns Detectable via SIA
+
+Anti-patterns that SIA's knowledge graph can help you detect and prevent.
+
+## Iron Laws
+
+1. **Never test mock behavior** — test real interfaces
+2. **Never test implementation** — test behavior
+3. **Never ignore known edge cases** — SIA remembers them for you
+
+## Anti-Pattern 1: Ignoring Known Bugs
+
+**Detection:** `sia_search` returns Bug entities for the area, but no tests cover them.
+
+**Gate function:** Before writing tests, query:
+```
+sia_search({ query: "bugs failures <area>", node_types: ["Bug"], limit: 10 })
+```
+
+If results exist, your test suite MUST include regression tests for each.
+
+**Violation:**
+```typescript
+// Bug entity exists: "Race condition in concurrent user creation"
+// Test suite has no concurrency test
+test("creates user", () => {
+  const user = createUser({ name: "Alice" });
+  expect(user.id).toBeDefined();
+});
+```
+
+**Fix:**
+```typescript
+test("creates user", () => { /* ... */ });
+
+// Regression test for known Bug entity
+test("handles concurrent user creation without race condition", async () => {
+  const [a, b] = await Promise.all([
+    createUser({ name: "Alice" }),
+    createUser({ name: "Bob" }),
+  ]);
+  expect(a.id).not.toBe(b.id);
+});
+```
+
+## Anti-Pattern 2: Testing Against Stale Interfaces
+
+**Detection:** `sia_by_file` shows the source file's entities have changed, but tests reference the old API.
+
+**Gate function:** Before writing tests:
+```
+sia_by_file({ file_path: "<source_file>" })
+```
+
+Compare the entity signatures against what your test expects. If the graph shows a newer interface, update your test.
+
+## Anti-Pattern 3: Violating Test Conventions
+
+**Detection:** `sia_search` returns Convention entities for testing patterns, but new tests don't follow them.
+
+**Gate function:**
+```
+sia_search({ query: "test conventions <area>", node_types: ["Convention"], limit: 5 })
+```
+
+If conventions exist (e.g., "use factory functions, not raw constructors"), follow them. Don't invent a new pattern.
+
+## Anti-Pattern 4: Testing Without Dependency Awareness
+
+**Detection:** `sia_expand` shows consumers of the code under test, but tests don't cover the integration points.
+
+**Gate function:** After refactoring:
+```
+sia_expand({ entity_id: "<refactored_entity>", depth: 1, edge_types: ["calls", "imports"] })
+```
+
+If N consumers depend on this code, verify at least the primary integration path is tested.
+
+## Anti-Pattern 5: Duplicating Solved Problems
+
+**Detection:** `sia_search` returns Solution entities that already address the test scenario.
+
+**Gate function:** Before writing a complex test helper:
+```
+sia_search({ query: "test helper <pattern>", node_types: ["Solution", "Convention"], limit: 5 })
+```
+
+If a helper or pattern already exists, use it instead of creating a duplicate.
+
+## Quick Reference
+
+| Anti-Pattern | SIA Query | What to Check |
+|---|---|---|
+| Ignoring known bugs | `sia_search` for Bug entities | Each bug has a regression test |
+| Stale interfaces | `sia_by_file` on source | Test matches current entity signatures |
+| Convention violation | `sia_search` for Convention | Tests follow established patterns |
+| Missing integration tests | `sia_expand` consumers | Primary integration paths covered |
+| Duplicate helpers | `sia_search` for Solution | Existing patterns reused |
+
+## Red Flags
+
+- **Zero Bug entities in a heavily-modified area** → Either the area is perfect (unlikely) or bugs aren't being captured. Run `sia-capture` first.
+- **Convention says "use X" but test uses Y** → Follow the convention. If the convention is wrong, update it — don't silently ignore it.
+- **sia_expand shows 10+ consumers but only 1 test** → High-risk area with low coverage. Flag to developer.

package/skills/sia-tour/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: sia-tour
+description: Provides an interactive guided tour of the knowledge graph — architecture, decisions, conventions, and known issues. Use for onboarding, exploring what SIA knows, or getting oriented in a new project.
+---
+
+# SIA Graph Tour
+
+Take a guided tour of what SIA knows about your project.
+
+## Usage
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts tour
+```
+
+## What It Shows
+
+1. **Architecture Overview** — major module clusters from community detection
+2. **Key Decisions** — architectural choices and their rationale
+3. **Coding Conventions** — patterns to follow
+4. **Known Issues** — active bugs to be aware of
+5. **Ingested Documentation** — docs in the knowledge graph
+
+## When To Use
+
+- After `/sia-setup` or `/sia-learn` — see what was discovered
+- When onboarding to a project — get the full picture
+- After a long break — refresh your memory of the project
+- When a new team member joins — share what SIA knows

package/skills/sia-upgrade/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: sia-upgrade
+description: Self-updates SIA to the latest version via npm, git, or binary strategies. Use when a new SIA version is available or when the user asks to upgrade.
+---
+
+# SIA Upgrade
+
+Update SIA to the latest version.
+
+## Quick Upgrade
+
+Use the `sia_upgrade` MCP tool:
+
+```
+sia_upgrade({})
+```
+
+Or with options:
+
+```
+sia_upgrade({
+  target_version: "0.2.0",
+  dry_run: true
+})
+```
+
+Parameters:
+- **target_version** (optional): Specific version to upgrade to (default: latest)
+- **dry_run** (optional): Preview what would change without applying
+
+## Upgrade Strategies
+
+SIA automatically selects the best upgrade strategy:
+
+1. **npm**: If installed via npm/bun package manager
+2. **git**: If running from a cloned repository (pulls latest)
+3. **binary**: If a custom release URL is configured
+
+## After Upgrading
+
+1. Run `sia-doctor` to verify the new version is working
+2. Database migrations run automatically on next startup
+3. Check release notes for any breaking changes