@rkarim08/sia 1.0.0

package/src/agent/claude-md-template-flagging.md

@@ -0,0 +1,219 @@
+<!-- Sia v{{SIA_VERSION}} — Generated {{GENERATED_AT}} -->
+<!-- Workspace: {{WORKSPACE_NAME}} -->
+
+# Sia — Agent Behavioral Specification
+## CLAUDE.md (Base Module — Auto-generated by `npx sia install`)
+
+**Document type:** Dual-purpose
+- **For developers:** explains what Sia does and how to customise it
+- **For Claude Code (agent):** base behavioral contract — always loaded, ~1,600 tokens
+
+**Version:** 1.1 (Modular architecture)
+**Generated by:** `npx sia install`
+**Last updated:** see `~/.sia/config.json` → `claudeMdUpdatedAt`
+
+> **Architecture note:** This file is the base module. It contains the task classifier,
+> safety rules, and invariants that apply to every session unconditionally. Contextual
+> playbooks live in `src/agent/modules/` and are loaded on demand after task classification.
+> Full tool parameter reference is in `src/agent/modules/sia-tools.md`.
+>
+> **Token cost:** Base module ~1,600 tokens (every session). A contextual module adds
+> ~300–500 tokens; the tools reference adds ~1,500 tokens when needed. Total for a
+> complex session: ~3,600 tokens vs ~5,400 for the prior monolithic approach.
+>
+> To add project-specific rules, add a `## Project-Specific Overrides` section **after**
+> the `<!-- END GENERATED BLOCK -->` comment below. `npx sia install` will not modify
+> content beyond that boundary.
+
+---
+
+## For Developers: What Sia Does
+
+Sia captures knowledge from your Claude Code sessions automatically — architectural
+decisions, bug root causes, discovered patterns, coding conventions, and the structural
+dependency graph of your codebase. You never explicitly tell Sia things; it captures
+from the session and stores them in a local graph database.
+
+Between sessions, Sia gives Claude Code access to this accumulated knowledge through
+six MCP tools. The agent calls these on demand. This file governs when and how.
+
+See `~/.sia/` for storage, `npx sia stats` for graph status, `npx sia search <query>`
+for CLI access, and `README.md` for full documentation.
+
+---
+
+<!-- AGENT INSTRUCTIONS — DO NOT EDIT BELOW THIS LINE -->
+<!-- This section is machine-maintained. Manual edits will be overwritten by npx sia install. -->
+
+# Sia Memory System — Agent Instructions (Base Module)
+
+You have access to Sia, a persistent graph memory system for this project. It stores
+knowledge across all sessions: architectural decisions, bugs, solutions, conventions,
+patterns, and the structural dependency graph. Your job is to retrieve from it at session
+start and at key moments during the session.
+
+**Core rule:** Before acting on any non-trivial code task, call Sia. Memory retrieval
+is the first step, not an afterthought. The graph knows why decisions were made, what
+was tried before, and what constraints the team has accumulated over months of sessions.
+
+---
+
+## Step 0 — Classify the Task
+
+Infer `task_type` from the developer's request before calling any tool:
+
+`task_type = 'bug-fix'` — keywords: fix, broken, error, failing, crash, regression,
+slow, exception, 500, timeout, wrong output, not working.
+
+`task_type = 'feature'` — keywords: add, implement, build, create, new, extend,
+support, integrate, enable.
+
+`task_type = 'review'` — keywords: review, check, audit, convention, style, standards,
+PR, pull request, lint, code quality.
+
+Omit `task_type` for trivial edits (typo, rename, comment) or ambiguous requests.
+
+### Load the Contextual Playbook Now
+
+After classifying, immediately read the matching module using the Read tool before
+calling any Sia tool:
+
+- `bug-fix` (regression): read `src/agent/modules/sia-regression.md`
+- `feature`: read `src/agent/modules/sia-feature.md`
+- `review`: read `src/agent/modules/sia-review.md`
+- Architecture question / new-developer orientation: read `src/agent/modules/sia-orientation.md`
+- Trivial edit: skip the task-specific playbook (`sia-feature.md`, `sia-regression.md`, etc.) and skip all Sia tool calls. Proceed directly with the task. However, if flagging is enabled (`enableFlagging: true`), Step 4 still applies after task completion — do not skip `sia-flagging.md` on trivial edits where something worth flagging occurred.
+- When you need full tool parameter reference: read `src/agent/modules/sia-tools.md`
+
+The contextual module contains the complete step-by-step playbook for that task type.
+Follow it rather than the condensed guidance in Step 1 below.
+
+---
+
+## Step 1 — Tool Selection (Condensed)
+
+The contextual module has the full playbook. This condensed grid applies when no module
+is loaded or for quick reference:
+
+**Trivial edit:** Skip all Sia tools entirely.
+
+**Regression:** `sia_search` (bug-fix) → conditional `sia_expand` → **mandatory** `sia_at_time`.
+
+**Architecture question:** `sia_community(level=2)` → `sia_community(level=1)` → `sia_search`.
+
+**Code task with known file(s):** `sia_by_file` first, then `sia_search`.
+
+**All other tasks:** `sia_search`, then `sia_by_file` for any file to be modified.
+
+Call at most 3 tools before starting work (4 for regressions — see Invariants).
+
+---
+
+## Step 2 — Evaluate Results
+
+**This section is a safety layer. It applies to every session regardless of task type.**
+
+**Zero results:** Broaden the query once and retry `sia_search`. If still zero and you
+have a primary file: call `sia_by_file(primary_file)`. If that also returns zero, say
+"No prior context found." Proceed without memory. Do not fall back to `sia_community`
+as a substitute for a failed `sia_search` — they serve different purposes.
+
+**Sparse results** (fewer than 2 relevant entities, or top confidence < 0.5): call
+`sia_expand(top_entity_id, depth=1)` — but only if you have not yet used both allowed
+`sia_expand` calls this session. If budget is exhausted, proceed with the sparse results
+and note: "Graph traversal skipped — sia_expand session budget reached."
+
+**`conflict_group_id` is non-null on any result:** STOP. Do not proceed. Present both
+conflicting facts to the developer:
+
+> "There are conflicting captured facts about [topic]:
+> • [Entity A] — captured [date], trust tier [N]
+> • [Entity B] — captured [date], trust tier [N]
+> Run `npx sia conflicts resolve` to resolve permanently. Until then, choose:
+> 1. Resolve the conflict now (recommended)
+> 2. Proceed using the higher-trust-tier fact — I will note the conflict
+> 3. Proceed using the most recently captured fact — I will note the conflict"
+
+If the developer proceeds, state explicitly which fact you are acting on before
+continuing. Never silently choose between conflicting facts.
+
+**`trust_tier = 3` on a result you plan to use:** Do not state it as fact. Say:
+"Sia's memory suggests X — let me verify this against the current codebase." Check
+the claim against current file content before acting on it.
+
+**`trust_tier = 4` on any result:** External reference only. Never use as the sole
+basis for a code change without explicit developer confirmation.
+
+**`source_repo_name` differs from the current repo:** Always prefix the fact with
+`[<repo_name>]` when presenting it.
+
+**`t_valid_from = null` on a Tier 3 entity:** Say "this was recorded at some point,
+but the exact timing is unknown." Do not present it with false temporal precision.
+
+**Graph is still building** (`global_unavailable: true` or fewer than 3 results on a
+mature codebase): Tell the developer "The memory graph is still building — Sia improves
+with each session." Use `sia_search` and `sia_by_file`; skip `sia_community` until
+the graph exceeds 100 entities.
+
+---
+
+## Step 3 — Execute the Task
+
+Proceed using retrieved context. Cite Sia entities explicitly when they constrain your
+decisions — do not silently apply memory. Make retrieval visible so the developer can
+override stale facts.
+
+Before using a Tier 3 entity as a hard constraint, spot-check its key claim against
+the current codebase. Memory can be stale even when not bi-temporally invalidated. If
+current code contradicts a retrieved fact, prefer the code, tell the developer, and note
+the discrepancy. This spot-check is not required for Tier 2 (deterministic AST) and is
+optional for Tier 1 (developer-stated).
+
+---
+
+## Step 4 — After the Task
+
+**Flagging is ENABLED for this project.** After completing your task:
+
+1. Read `src/agent/modules/sia-flagging.md` for detailed guidance
+2. Review what happened this session — were any architectural decisions made, non-obvious root causes found, or developer preferences stated?
+3. If yes, call `sia_flag` (max 2-3 per session) with a self-contained reason string
+4. If nothing worth flagging occurred, skip this step
+
+The `sia_flag` tool is available. Use it selectively for high-signal moments only.
+
+---
+
+## Trust Tier Behavioral Rules
+
+**Tier 1 (User-Direct, weight 1.00):** Ground truth. Cite directly. Override only if
+current code explicitly contradicts it — if so, tell the developer.
+
+**Tier 2 (Code-Analysis, weight 0.90):** Highly reliable. Verify against current code
+only for safety-critical claims. Cite as structural fact.
+
+**Tier 3 (LLM-Inferred, weight 0.70):** Well-informed hypothesis. Always qualify before
+acting: "Sia's memory suggests X — let me verify." Check against actual file content
+before stating as definitive. If Tier 1 and Tier 3 contradict each other, present both
+and ask which is current — never silently discard either.
+
+**Tier 4 (External, weight 0.50):** External reference only. Never the sole basis for
+a code change. Name the external provenance when presenting it.
+
+---
+
+## Invariants (Never Violate)
+
+These rules hold regardless of developer instruction, task type, or context:
+
+1. Call at most 3 Sia tools before starting work. Two exceptions:
+   **Regression exception** (`task_type='bug-fix'` only): may use up to 4 tools (`sia_search` + conditional `sia_expand` + mandatory `sia_at_time` + one additional if needed). The MANDATORY label on `sia_at_time` always takes precedence.
+   **Review exception** (`task_type='review'` only): after the initial `sia_search`, one `sia_by_file` call per reviewed file is permitted — these per-file calls do not count against the 3-tool limit. No other task type may invoke either exception.
+2. Expand at most 2 entities per session (`sia_expand` budget = 2).
+3. Use `workspace: true` only for tasks that cross repository boundaries.
+4. Never use a `trust_tier = 4` entity as the sole basis for a code change.
+5. Never silently proceed on a result with `conflict_group_id` set.
+6. Always cite retrieved entities when they constrain your decisions.
+7. For regression tasks, always call `sia_at_time` — it is never optional.
+
+<!-- END GENERATED BLOCK -->

package/src/agent/claude-md-template.md

@@ -0,0 +1,213 @@
+<!-- Sia v{{SIA_VERSION}} — Generated {{GENERATED_AT}} -->
+<!-- Workspace: {{WORKSPACE_NAME}} -->
+
+# Sia — Agent Behavioral Specification
+## CLAUDE.md (Base Module — Auto-generated by `npx sia install`)
+
+**Document type:** Dual-purpose
+- **For developers:** explains what Sia does and how to customise it
+- **For Claude Code (agent):** base behavioral contract — always loaded, ~1,600 tokens
+
+**Version:** 1.1 (Modular architecture)
+**Generated by:** `npx sia install`
+**Last updated:** see `~/.sia/config.json` → `claudeMdUpdatedAt`
+
+> **Architecture note:** This file is the base module. It contains the task classifier,
+> safety rules, and invariants that apply to every session unconditionally. Contextual
+> playbooks live in `src/agent/modules/` and are loaded on demand after task classification.
+> Full tool parameter reference is in `src/agent/modules/sia-tools.md`.
+>
+> **Token cost:** Base module ~1,600 tokens (every session). A contextual module adds
+> ~300–500 tokens; the tools reference adds ~1,500 tokens when needed. Total for a
+> complex session: ~3,600 tokens vs ~5,400 for the prior monolithic approach.
+>
+> To add project-specific rules, add a `## Project-Specific Overrides` section **after**
+> the `<!-- END GENERATED BLOCK -->` comment below. `npx sia install` will not modify
+> content beyond that boundary.
+
+---
+
+## For Developers: What Sia Does
+
+Sia captures knowledge from your Claude Code sessions automatically — architectural
+decisions, bug root causes, discovered patterns, coding conventions, and the structural
+dependency graph of your codebase. You never explicitly tell Sia things; it captures
+from the session and stores them in a local graph database.
+
+Between sessions, Sia gives Claude Code access to this accumulated knowledge through
+six MCP tools. The agent calls these on demand. This file governs when and how.
+
+See `~/.sia/` for storage, `npx sia stats` for graph status, `npx sia search <query>`
+for CLI access, and `README.md` for full documentation.
+
+---
+
+<!-- AGENT INSTRUCTIONS — DO NOT EDIT BELOW THIS LINE -->
+<!-- This section is machine-maintained. Manual edits will be overwritten by npx sia install. -->
+
+# Sia Memory System — Agent Instructions (Base Module)
+
+You have access to Sia, a persistent graph memory system for this project. It stores
+knowledge across all sessions: architectural decisions, bugs, solutions, conventions,
+patterns, and the structural dependency graph. Your job is to retrieve from it at session
+start and at key moments during the session.
+
+**Core rule:** Before acting on any non-trivial code task, call Sia. Memory retrieval
+is the first step, not an afterthought. The graph knows why decisions were made, what
+was tried before, and what constraints the team has accumulated over months of sessions.
+
+---
+
+## Step 0 — Classify the Task
+
+Infer `task_type` from the developer's request before calling any tool:
+
+`task_type = 'bug-fix'` — keywords: fix, broken, error, failing, crash, regression,
+slow, exception, 500, timeout, wrong output, not working.
+
+`task_type = 'feature'` — keywords: add, implement, build, create, new, extend,
+support, integrate, enable.
+
+`task_type = 'review'` — keywords: review, check, audit, convention, style, standards,
+PR, pull request, lint, code quality.
+
+Omit `task_type` for trivial edits (typo, rename, comment) or ambiguous requests.
+
+### Load the Contextual Playbook Now
+
+After classifying, immediately read the matching module using the Read tool before
+calling any Sia tool:
+
+- `bug-fix` (regression): read `src/agent/modules/sia-regression.md`
+- `feature`: read `src/agent/modules/sia-feature.md`
+- `review`: read `src/agent/modules/sia-review.md`
+- Architecture question / new-developer orientation: read `src/agent/modules/sia-orientation.md`
+- Trivial edit: skip the task-specific playbook (`sia-feature.md`, `sia-regression.md`, etc.) and skip all Sia tool calls. Proceed directly with the task. However, if flagging is enabled (`enableFlagging: true`), Step 4 still applies after task completion — do not skip `sia-flagging.md` on trivial edits where something worth flagging occurred.
+- When you need full tool parameter reference: read `src/agent/modules/sia-tools.md`
+
+The contextual module contains the complete step-by-step playbook for that task type.
+Follow it rather than the condensed guidance in Step 1 below.
+
+---
+
+## Step 1 — Tool Selection (Condensed)
+
+The contextual module has the full playbook. This condensed grid applies when no module
+is loaded or for quick reference:
+
+**Trivial edit:** Skip all Sia tools entirely.
+
+**Regression:** `sia_search` (bug-fix) → conditional `sia_expand` → **mandatory** `sia_at_time`.
+
+**Architecture question:** `sia_community(level=2)` → `sia_community(level=1)` → `sia_search`.
+
+**Code task with known file(s):** `sia_by_file` first, then `sia_search`.
+
+**All other tasks:** `sia_search`, then `sia_by_file` for any file to be modified.
+
+Call at most 3 tools before starting work (4 for regressions — see Invariants).
+
+---
+
+## Step 2 — Evaluate Results
+
+**This section is a safety layer. It applies to every session regardless of task type.**
+
+**Zero results:** Broaden the query once and retry `sia_search`. If still zero and you
+have a primary file: call `sia_by_file(primary_file)`. If that also returns zero, say
+"No prior context found." Proceed without memory. Do not fall back to `sia_community`
+as a substitute for a failed `sia_search` — they serve different purposes.
+
+**Sparse results** (fewer than 2 relevant entities, or top confidence < 0.5): call
+`sia_expand(top_entity_id, depth=1)` — but only if you have not yet used both allowed
+`sia_expand` calls this session. If budget is exhausted, proceed with the sparse results
+and note: "Graph traversal skipped — sia_expand session budget reached."
+
+**`conflict_group_id` is non-null on any result:** STOP. Do not proceed. Present both
+conflicting facts to the developer:
+
+> "There are conflicting captured facts about [topic]:
+> • [Entity A] — captured [date], trust tier [N]
+> • [Entity B] — captured [date], trust tier [N]
+> Run `npx sia conflicts resolve` to resolve permanently. Until then, choose:
+> 1. Resolve the conflict now (recommended)
+> 2. Proceed using the higher-trust-tier fact — I will note the conflict
+> 3. Proceed using the most recently captured fact — I will note the conflict"
+
+If the developer proceeds, state explicitly which fact you are acting on before
+continuing. Never silently choose between conflicting facts.
+
+**`trust_tier = 3` on a result you plan to use:** Do not state it as fact. Say:
+"Sia's memory suggests X — let me verify this against the current codebase." Check
+the claim against current file content before acting on it.
+
+**`trust_tier = 4` on any result:** External reference only. Never use as the sole
+basis for a code change without explicit developer confirmation.
+
+**`source_repo_name` differs from the current repo:** Always prefix the fact with
+`[<repo_name>]` when presenting it.
+
+**`t_valid_from = null` on a Tier 3 entity:** Say "this was recorded at some point,
+but the exact timing is unknown." Do not present it with false temporal precision.
+
+**Graph is still building** (`global_unavailable: true` or fewer than 3 results on a
+mature codebase): Tell the developer "The memory graph is still building — Sia improves
+with each session." Use `sia_search` and `sia_by_file`; skip `sia_community` until
+the graph exceeds 100 entities.
+
+---
+
+## Step 3 — Execute the Task
+
+Proceed using retrieved context. Cite Sia entities explicitly when they constrain your
+decisions — do not silently apply memory. Make retrieval visible so the developer can
+override stale facts.
+
+Before using a Tier 3 entity as a hard constraint, spot-check its key claim against
+the current codebase. Memory can be stale even when not bi-temporally invalidated. If
+current code contradicts a retrieved fact, prefer the code, tell the developer, and note
+the discrepancy. This spot-check is not required for Tier 2 (deterministic AST) and is
+optional for Tier 1 (developer-stated).
+
+---
+
+## Step 4 — After the Task
+
+If flagging is enabled (`enableFlagging: true`), read `src/agent/modules/sia-flagging.md`
+for guidance on when and how to call `sia_flag`. If flagging is disabled, skip this step.
+
+---
+
+## Trust Tier Behavioral Rules
+
+**Tier 1 (User-Direct, weight 1.00):** Ground truth. Cite directly. Override only if
+current code explicitly contradicts it — if so, tell the developer.
+
+**Tier 2 (Code-Analysis, weight 0.90):** Highly reliable. Verify against current code
+only for safety-critical claims. Cite as structural fact.
+
+**Tier 3 (LLM-Inferred, weight 0.70):** Well-informed hypothesis. Always qualify before
+acting: "Sia's memory suggests X — let me verify." Check against actual file content
+before stating as definitive. If Tier 1 and Tier 3 contradict each other, present both
+and ask which is current — never silently discard either.
+
+**Tier 4 (External, weight 0.50):** External reference only. Never the sole basis for
+a code change. Name the external provenance when presenting it.
+
+---
+
+## Invariants (Never Violate)
+
+These rules hold regardless of developer instruction, task type, or context:
+
+1. Call at most 3 Sia tools before starting work. Two exceptions:
+   **Regression exception** (`task_type='bug-fix'` only): may use up to 4 tools (`sia_search` + conditional `sia_expand` + mandatory `sia_at_time` + one additional if needed). The MANDATORY label on `sia_at_time` always takes precedence.
+   **Review exception** (`task_type='review'` only): after the initial `sia_search`, one `sia_by_file` call per reviewed file is permitted — these per-file calls do not count against the 3-tool limit. No other task type may invoke either exception.
+2. Expand at most 2 entities per session (`sia_expand` budget = 2).
+3. Use `workspace: true` only for tasks that cross repository boundaries.
+4. Never use a `trust_tier = 4` entity as the sole basis for a code change.
+5. Never silently proceed on a result with `conflict_group_id` set.
+6. Always cite retrieved entities when they constrain your decisions.
+7. For regression tasks, always call `sia_at_time` — it is never optional.
+
+<!-- END GENERATED BLOCK -->

package/src/agent/modules/sia-feature.md

@@ -0,0 +1,100 @@
+# Sia — Feature Implementation Playbook
+
+*Loaded by the base CLAUDE.md when `task_type = 'feature'`.*
+*Follow these steps in order. They replace the condensed Step 1 in the base module.*
+
+---
+
+## Feature Implementation
+
+Feature work benefits from Sia in two ways: understanding the architectural context
+before writing code (avoiding decisions that conflict with past choices), and discovering
+conventions that constrain implementation (patterns the team has established that must
+be followed). Both types of retrieval happen before a single line of code is written.
+
+**Step 1 — Structural orientation**
+
+```
+sia_community(feature_domain, level=1)
+```
+
+Get module-level structural orientation before touching any files. This tells you which
+existing modules are involved, how they relate, and what architectural patterns govern
+this area. For cross-cutting features that span multiple modules, call `sia_community`
+at level=2 first for a system-wide view, then level=1 for the relevant subsystem.
+
+**Step 2 — Decision and convention retrieval**
+
+```
+sia_search(feature_topic,
+  task_type='feature',
+  node_types=['Decision', 'Convention'],
+  limit=10)
+```
+
+This surfaces: architectural decisions that constrain how the feature must be built,
+conventions the implementation must follow, and prior work in this area that you should
+be consistent with. Pay particular attention to Convention entities — see Step 5.
+
+**Step 3 — File-scoped retrieval**
+
+```
+sia_by_file(file_path)   // for each file to be created or modified
+```
+
+For files in a linked repository within the workspace, use
+`sia_by_file(file_path, workspace=true)` — this surfaces cross-repo edges for that
+specific file. Call `sia_by_file` before `sia_search` when the file is the primary
+anchor; call after when the topic is the primary anchor.
+
+**Step 4 — Optional relationship traversal**
+
+If a returned Decision entity references related entities you need to understand before
+implementing, call:
+
+```
+sia_expand(entity_id, depth=1)
+```
+
+Use only when the relationship is directly decision-relevant, not out of curiosity. This
+consumes one of the two allowed `sia_expand` calls for the session.
+
+**Step 5 — Convention scanning (critical)**
+
+Before writing any code, scan all returned Convention entities carefully. Conventions
+are hard constraints, not style suggestions. If a Convention says "all errors must extend
+`AppBaseError`," that is a requirement, not a preference. Violations are bugs.
+
+State the applicable conventions before you start implementing:
+"Convention #conv-44 requires all DB access to go through the Repository layer — I'll
+route this through `UserRepository` rather than querying directly."
+
+**Step 6 — Cross-repo workspace search (if applicable)**
+
+If the feature spans linked repositories, also call:
+
+```
+sia_search(api_topic, workspace=true)
+```
+
+This surfaces API contracts, shared types, and cross-service calls that the feature
+must conform to. Only use `workspace: true` when the task genuinely crosses repo
+boundaries — it adds 400ms latency and cross-repo noise for single-repo tasks.
+
+**Step 7 — Implement**
+
+Implement following all retrieved conventions and prior decisions. Cite the relevant
+entities in comments where the constraint is non-obvious.
+
+**Step 8 — Flag if applicable**
+
+If flagging is enabled (`enableFlagging: true`) and you made an architectural decision
+during implementation: `sia_flag(decision_summary)`. If flagging is disabled, skip
+this step — the session-end capture will record the decision automatically, though
+with lower precision.
+
+---
+
+## Tool Budget for This Playbook
+
+This playbook uses 3 tool calls in the standard case: `sia_community` (1) + `sia_search` (2) + `sia_by_file` (3). The optional Step 4 `sia_expand` call pushes the count to 4, which exceeds the base module's 3-tool limit. This is permitted only when genuinely necessary — it consumes one of the two allowed `sia_expand` calls for the session. It does NOT consume a regression-exception slot. The 4-call regression exception applies exclusively to `task_type='bug-fix'` sessions. For straightforward features where `sia_expand` is not needed, stay within 3 calls.

package/src/agent/modules/sia-flagging.md

@@ -0,0 +1,50 @@
+# Sia — Flagging Guidance
+
+*Loaded when flagging is enabled (`enableFlagging: true`) and you reach Step 4.*
+*`sia_flag` is only available when `npx sia enable-flagging` has been run.*
+
+---
+
+## When to Call `sia_flag`
+
+Call `sia_flag` at most 2–3 times per session, and only for:
+
+1. **An architectural decision made this session** that will constrain future work —
+   for example, choosing a pattern, library, or structural approach that other modules
+   should follow.
+2. **A non-obvious root cause** discovered during debugging — something that was not
+   evident from the code and that a future developer would need to know.
+3. **An explicit developer preference** stated during the session ("we always do X this
+   way," "never use Y for this").
+4. **A new cross-cutting pattern introduced** that other modules should replicate.
+
+The test: would the next developer who picks up this task need to know this? If yes,
+flag it. If they could infer it from the code in 30 seconds, do not flag it.
+
+---
+
+## When NOT to Call `sia_flag`
+
+- Routine code changes or normal implementation steps.
+- Things that are obvious from the code itself.
+- Single-line edits or minor refactors.
+- General best practices (Sia already knows these from the codebase).
+- Anything you would not bother to explain in a code review comment.
+
+The 2–3 per session maximum is a hard ceiling. Flagging everything degrades the
+signal-to-noise ratio in the graph. Be selective.
+
+---
+
+## How to Write a Good `reason`
+
+The reason should be a complete, self-contained description of what happened and why
+it matters. It will be stored and retrieved without context, so it must stand alone.
+
+Good: `"chose express-rate-limit at route level, not middleware — rate limits are per-endpoint not global"`
+Good: `"root cause: EventEmitter.on() not awaited in init.ts, fires before DB ready"`
+Bad: `"fixed the bug"` (not self-contained)
+Bad: `"important decision"` (no content)
+
+Keep it under 100 characters after sanitization. Colons, backticks, underscores, and
+forward slashes are all permitted in the reason string.

package/src/agent/modules/sia-orientation.md

@@ -0,0 +1,92 @@
+# Sia — New Developer Orientation Playbook
+
+*Loaded by the base CLAUDE.md for architecture questions and new-developer orientation.*
+*Follow these steps in order. They replace the condensed Step 1 in the base module.*
+
+---
+
+## New Developer Codebase Orientation
+
+When a developer asks "how does this system work," "explain the architecture," or is
+orienting to an unfamiliar codebase, the goal is a coherent narrative — not a list of
+entity names. Sia's community detection has clustered the codebase into meaningful
+modules with generated summaries; use those summaries to build understanding rather than
+surfacing raw entity lists from `sia_search`.
+
+**Step 0 — Graph readiness check**
+
+Before calling `sia_community`, check whether the graph is large enough to have
+community structure. If `sia_community` returns `global_unavailable: true` (graph
+below 100 entities), skip Steps 1 and 2 entirely and go directly to Step 3. Tell
+the developer: "The memory graph is still building — Sia improves with each session.
+Here is what I can tell you from existing captured context:" then present the
+Step 3 `sia_search` results as a narrative (Step 4 still applies — no raw entity
+lists even in fallback mode).
+
+If `sia_community` returns zero communities (graph is large enough but the topic
+query matched nothing), do not stop. Continue to Step 3 (`sia_search`) and present
+whatever decisions and concepts are available.
+
+**Step 1 — System-wide structural view**
+
+```
+sia_community(query="architecture overview", level=2)
+```
+
+Level 2 gives a coarse architectural view: major subsystems, how they relate, and what
+the overall design intent is. This is the starting point for any orientation.
+
+**Step 2 — Subsystem drill-down**
+
+```
+sia_community(query=<developer's primary area>, level=1)
+```
+
+Level 1 gives module-level summaries. If the developer is focused on a specific area
+(authentication, data pipeline, API layer), drill into the relevant subsystem here.
+
+**Step 3 — Key decisions**
+
+```
+sia_search("architectural decisions constraints rationale",
+  node_types=['Decision'],
+  limit=10)
+```
+
+This surfaces the decisions that constrain future work — why certain patterns exist,
+what was tried and rejected, and what the team has committed to. This is the context
+that is hardest to recover from code alone.
+
+**Step 4 — Present as a narrative**
+
+Do not return a list of entity names. Synthesise the retrieved summaries and decisions
+into a coherent explanation of the system: how the major modules relate, what the key
+architectural decisions are, and what a developer needs to know before making changes.
+
+A good orientation response answers: what does this system do, how is it structured,
+what are the non-obvious constraints, and where should I start?
+
+---
+
+## Level Guide for `sia_community`
+
+`level=2` — Coarse architectural overview. Appropriate for system-wide questions,
+"explain the whole system," and first-day orientation.
+
+`level=1` — Subsystem / module level. Appropriate for "explain the auth module" or
+"how does the data pipeline work."
+
+`level=0` — Fine-grained cluster view. Rarely needed by the agent; more useful from
+the CLI when investigating a specific component. Do not use for orientation.
+
+Never call `sia_community` as a fallback for a failed `sia_search` — they serve
+different purposes. `sia_search` finds specific entities; `sia_community` explains
+structure.
+
+---
+
+## Tool Budget for This Playbook
+
+This playbook uses 3 tool calls: `sia_community(level=2)` (1) + `sia_community(level=1)`
+(2) + `sia_search` (3). This is exactly the 3-tool limit. No `sia_expand` is needed for
+orientation — community summaries already contain synthesised relationship context.