@veedubin/neuralgentics 0.13.5 → 0.13.7

package/.opencode/skills/kanban-board-manager/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: kanban-board-manager
+description: Manages the Boomerang kanban board in TASKS.md. Creates, moves, and audits cards across seven statuses (triage, todo, ready, running, blocked, done, archived). Seeded by the orchestrator from a roadmap; queried by the orchestrator to find ready cards for dispatch; updated by workers when they complete a card. The board is the durable source of truth for "what is being worked on."
+---
+
+# Kanban Board Manager
+
+## Description
+
+The kanban board lives in the project's `TASKS.md` file. It has seven statuses (Hermes-compatible) and supports dependency links between cards. The board manager is the **only** agent that mutates the board. Workers report status changes through it; the orchestrator queries it to find ready cards.
+
+## When to Use This Skill
+
+- After the architect writes a roadmap → seed the board with one card per task.
+- A worker has finished a card → move it `running → done` with evidence.
+- A worker is stuck → move it `running → blocked` with a reason.
+- The orchestrator needs to find `ready` cards → query the board.
+- The user asks "what's the status?" → render the board.
+- A card needs to be broken into smaller cards.
+- A card needs to be re-architect-ed.
+- A card needs to be requeued to "next session" (moved to `todo` with a reason).
+
+## Card Schema
+
+Each card in `TASKS.md` uses this exact format. The board manager is responsible for keeping the format consistent.
+
+```markdown
+### T-001 · <task title>
+- **Status:** <triage|todo|ready|running|blocked|done|archived>
+- **Assignee:** <agent profile, e.g. boomerang-coder>
+- **Phase:** <phase name from roadmap>
+- **Roadmap:** `docs/roadmap-<proj>.md#task-1-1`
+- **Goal:** one-sentence goal
+- **Acceptance:** testable criteria (bullet list)
+- **Scope IN:** bullet list
+- **Scope OUT:** bullet list, with escalation target
+- **Depends on:** T-002, T-003 (or `none`)
+- **Blocks:** T-004, T-005 (or `none`)
+- **Created:** YYYY-MM-DD
+- **Updated:** YYYY-MM-DD
+- **Wrap-up evidence:**
+  - changed_files: [...]
+  - verification: [...]
+  - residual_risk: [...]
+  - summary: one-paragraph closeout
+```
+
+Cards are grouped by status in `TASKS.md` with `## <Status>` headers (e.g. `## Triage`, `## Todo`, `## Ready`, `## Running`, `## Blocked`, `## Done`, `## Archived`). The board manager keeps the seven sections in this order.
+
+## Operations
+
+### seed_from_roadmap(roadmap_path)
+
+Called by the orchestrator after the architect writes a roadmap. Reads `docs/roadmap-<proj>.md`, creates one card per task with:
+- Status defaults to `todo` (unless the task has no dependencies, in which case `ready`)
+- Assignee defaults to the profile listed in the roadmap
+- ID assigned sequentially (`T-001`, `T-002`, ...)
+- All other fields populated from the roadmap section
+
+The board manager **does not** skip this step. The roadmap is the contract; the board is the working copy.
+
+### list_by_status(status)
+
+Returns all card IDs and titles with the given status. Used by the orchestrator to find `ready` cards for dispatch.
+
+### find_ready_cards()
+
+Returns all cards with status `ready` AND all dependencies marked `done`. These are dispatchable.
+
+### claim(card_id, worker)
+
+Moves a card `ready → running` and stamps the worker as the assignee. Returns the card's full content for the worker's Context Package.
+
+### complete(card_id, evidence)
+
+Moves a card `running → done`. The `evidence` argument is the structured wrap-up:
+
+```json
+{
+  "summary": "one-paragraph closeout",
+  "changed_files": ["path/to/file.py"],
+  "verification": ["pytest tests/x.py", "npm run lint"],
+  "residual_risk": ["what was not tested", "what still needs human review"],
+  "retry_notes": "what failed before if this was a retry"
+}
+```
+
+The board manager appends the evidence to the card's `Wrap-up evidence` block and stamps the `Updated` date.
+
+### block(card_id, reason)
+
+Moves a card `running → blocked` (or `todo → blocked`) with a `Blocked reason` field. The orchestrator surfaces blocked cards to the user.
+
+### unblock(card_id, resolution)
+
+Moves a card `blocked → ready` (or `todo`) with a `Resolution` field describing what changed.
+
+### break_down(card_id, new_cards)
+
+Splits a card into multiple smaller cards. Closes the original as `archived` with reason "broken into T-X, T-Y, T-Z" and creates the new cards with `todo` status. Dependencies are re-pointed.
+
+### rearchitect(card_id, question)
+
+Moves a card `todo → triage` with a `Re-architect question` field. The orchestrator will route the card back to the architect with this question as part of the Context Package.
+
+### requeue(card_id, reason)
+
+Moves a card to `todo` with a `Requeue reason` field. Use this for cards that are out of scope for the current session but should be revisited later.
+
+## Audit Operations
+
+### walk_board()
+
+Renders a human-readable summary of all cards grouped by status. Used by the orchestrator at wrap-up and by the user for status checks.
+
+### find_unaccounted()
+
+Returns all cards that are not `done` or `archived` AND have not been updated in the last 7 days. The orchestrator uses this at wrap-up to decide what to break, re-architect, or requeue.
+
+### find_blocked()
+
+Returns all `blocked` cards. The orchestrator surfaces these to the user; they need human input.
+
+### find_done_without_evidence()
+
+Returns all `done` cards where `Wrap-up evidence` is missing or incomplete. The orchestrator uses this to verify worker wrap-ups.
+
+## Implementation Notes
+
+- The board manager operates on `TASKS.md` directly. The file is the board. There is no separate database.
+- Card IDs are stable. Once assigned, an ID is never reused.
+- `Updated` is stamped on every status change.
+- The board manager does NOT decide what to work on. The orchestrator decides that. The board manager only records decisions.
+- Workers report status changes through the board manager; they do not edit `TASKS.md` directly.
+
+## Model
+
+Use **Gemini** for routine board operations. The board manager is mostly mechanical (move status, append evidence) and does not need heavy reasoning.
+
+## Anti-Patterns
+
+- **Do not** let a worker edit `TASKS.md` directly. All changes go through the board manager.
+- **Do not** store card content in chat context. Always read from `TASKS.md` and write back to `TASKS.md`.
+- **Do not** create a card without a roadmap link (except in `triage`, where the card IS the rough idea).
+- **Do not** move a card to `done` without evidence. The board manager should refuse and prompt the worker for the wrap-up JSON.
+- **Do not** auto-promote a card to `ready` if its dependencies are not all `done`. The orchestrator (or board manager's `find_ready_cards()`) checks this explicitly.
+
+## Card Granularity Rules (Added Session 23)
+
+These rules govern **how fine-grained a card should be**. Over-broad cards waste context and degrade worker output.
+
+### Rule G1: One logical change per card
+A card's "Acceptance" should fit in **one logical change**. Examples of properly-scoped cards:
+- ✅ "Fix silent error swallowing in 7 Scan loops in store package"
+- ✅ "Fix CountMemories broken primary query"
+- ✅ "Add regression test for CountMemories"
+- ❌ "Refactor memory store package" (too broad — 1768 LOC god-file)
+- ❌ "Fix memory store bugs" (too vague)
+
+If a logical change touches multiple files in the same module, that's fine — one card, one dispatch. But if it touches multiple unrelated concerns (e.g., error handling + a new feature + perf), that's three cards.
+
+### Rule G2: Cards that need linting spawn a separate card
+If a card's "Scope IN" includes "touch N files" and the touched files will need lint/format work, the card's wrap-up should list those files explicitly so a follow-up `T-LINT-XXX` card can dispatch to a `boomerang-linter` agent. Do not bundle the lint work into the coder's dispatch.
+
+Card convention:
+- Logic-fix cards: `T-NNN · <verb> <thing> — <one-line summary>`
+- Lint-only cards: `T-LINT-NNN · <tool> <files> after <T-XXX>`
+
+### Rule G3: Cards that span new code + tests split
+A "fix this bug" card is fine to include "add regression test" in the same dispatch (the test proves the fix). But a "fill coverage gap" card that is purely about adding tests to existing code should be `T-TEST-NNN`, not bundled with a refactor.
+
+### Rule G4: Refactor of N>1 file splits into N or more cards
+A refactor that splits a 1768-LOC file into 10 files is **at least 10 cards** (one per new file extraction), executed sequentially. Don't try to do all 10 in one dispatch.

package/.opencode/skills/skill-self-audit/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: skill-self-audit
+description: End-of-cycle audit that detects repeated processes and creates skills for them. Invoked by the orchestrator before wrap-up. If a process was repeated more than once during the cycle, the orchestrator invokes boomerang-agent-builder to formalize it as a skill before signing off.
+---
+
+# Skill Self-Audit
+
+## Description
+
+The orchestrator runs this audit at the end of every cycle. The audit scans the cycle for processes that were repeated more than once — and if any are found, the orchestrator creates a skill for them. This is how the Boomerang v3 skill library grows organically: as patterns repeat, they get formalized.
+
+## The Rule
+
+> **If we did a process more than once this cycle, it should be a skill.**
+
+This is not optional. The orchestrator's wrap-up protocol includes this step explicitly. The user said:
+
+> "We need to at the end of every boomerang look at if we did a process if it would make sense to make it a skill. We need this also built in."
+
+So this skill is built in.
+
+## When to Use This Skill
+
+- The orchestrator is about to wrap up a cycle (every cycle)
+- The user says "/boomerang-handoff" or the cycle is naturally ending
+- A session is being terminated
+- The user explicitly invokes "skill audit" or "self-audit"
+
+## Audit Process
+
+### 1. Review the cycle's actions
+
+Walk through the orchestrator's actions in the current cycle:
+- Memory queries
+- Architect dispatches
+- Worker dispatches (Task tool calls)
+- File reads / searches
+- Skill invocations
+- Context Package builds
+- Status changes
+
+Look for **processes that recurred** — meaning the same multi-step pattern was executed more than once, even if the targets were different.
+
+Examples of "recurring process":
+- Built 3 different Context Packages for 3 different cards (→ the "build Context Package" process should be a skill)
+- Dispatched 4 coder tasks each with the same permission-check step (→ the "broker permission gate" should be a skill)
+- Read AGENTS.md, TASKS.md, HANDOFF.md at the start of two different cycles (→ already a skill: the Session Start Protocol)
+- Had to look up the same docs/roadmap path 5 times during dispatch (→ the orchestrator should pin the roadmap as a session variable)
+- Translated the same kind of card evidence into the same kanban-board-manager call 6 times (→ the wrap-up evidence structure is already formalized; no new skill needed)
+
+Examples of "not recurring" (do NOT make a skill):
+- Read 1 file once to get context
+- Asked the architect to design 1 thing
+- Performed 1 dispatch
+
+### 2. For each recurring process, decide
+
+Ask three questions:
+
+1. **Is the process already a skill?** If yes, no action. Example: "build Context Package" is a documented pattern in the orchestrator skill, not a new skill.
+2. **Is the process too narrow to be a skill?** A skill should be reusable across projects and sessions. If the process is project-specific or one-off, document it in HANDOFF.md instead of creating a skill.
+3. **Would formalizing it reduce token cost or increase reliability?** If yes, create the skill. If it's just a "nice to have," defer.
+
+If all three answer "no," don't create a skill.
+
+### 3. If a new skill is warranted
+
+Invoke the `boomerang-agent-builder` skill with:
+
+- **Process name** — what to call the new skill
+- **Process description** — what it does, when to use it
+- **Process steps** — the exact sequence of operations
+- **Inputs** — what the skill takes
+- **Outputs** — what the skill returns
+- **Example invocation** — a worked example
+
+`boomerang-agent-builder` handles the rest: frontmatter, naming convention, syncing across the 3 skill locations, validating with `npm run fix-perms` and yaml_check.
+
+### 4. If a skill should be UPDATED (not created)
+
+If an existing skill is being applied in a way that wasn't anticipated, the orchestrator should:
+- Note the deviation in HANDOFF.md
+- Add a TODO to the kanban board for "improve <skill-name> to handle <scenario>"
+- Continue with the current cycle; do not block on the skill update
+
+### 5. Record the audit result
+
+Whether or not a skill was created, the audit result is recorded:
+
+- **Skills created this cycle:** T-XXX → new skill name
+- **Skills marked for improvement:** T-YYY → skill name → reason
+- **No new skills needed:** a one-liner explaining why the cycle's processes were all unique or already covered
+
+This is saved to memoryManager with `project` metadata so the next session can see what was learned.
+
+## Output Format
+
+The audit returns a single Markdown block:
+
+```markdown
+## Skill Self-Audit Result
+
+### Skills Created
+- **<skill-name>** — <one-line description>
+  - Triggered by: <which actions in the cycle>
+  - Replaces: <ad-hoc process description>
+
+### Skills Marked for Improvement
+- **<skill-name>** — <gap description>
+  - Tracked as: T-XXX on the kanban board
+
+### No Action Needed
+- <one-liner per non-issue, e.g. "The Context Package template is already in boomerang-orchestrator SKILL.md">
+
+### Cycle Summary
+- Total actions reviewed: N
+- Recurring processes found: N
+- Skills created: N
+- Skills marked for improvement: N
+```
+
+## Anti-Patterns
+
+- **Do not** create a skill for a process that was performed only once. "Once" is data, not a pattern.
+- **Do not** create a skill that overlaps with an existing skill. Update the existing one instead.
+- **Do not** create skills for project-specific processes. Those belong in HANDOFF.md or the project's own docs.
+- **Do not** skip the audit. The user asked for it to be "built in," and it is.
+
+## Model
+
+Use **Gemini** for the audit reasoning. Skill creation itself (via `boomerang-agent-builder`) uses the agent-builder's recommended model (deepseek-v4-pro:cloud or higher).

package/.opencode/skills/todo-list-updater/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: todo-list-updater
+description: Refreshes the project's todo list (TASKS.md or its Current Phase section) to reflect the current cycle's state. Invoked by the orchestrator at end of cycle, when a phase transitions, or when the user asks to clean up the todo list. Marks done items, removes stale items, adds newly discovered items, and keeps the file scannable for the next cycle.
+---
+
+# Todo List Updater
+
+## Description
+
+The todo list lives in `TASKS.md` (or in a project-specific location if the project overrides the convention). The orchestrator invokes this skill to keep the file current. The file is the canonical "what are we working on right now" — chat scrollback and memory are not.
+
+## When to Use This Skill
+
+- The orchestrator is about to wrap up a cycle
+- A phase transition is happening (a major milestone reached)
+- The user asks "what's the todo list?" or "clean up the todos"
+- Several items have completed since the last update
+- New items were discovered during the cycle that need to be tracked
+
+## The File Convention
+
+`TASKS.md` has this structure. The updater preserves the structure; it does not impose it on a project that uses a different convention.
+
+```markdown
+# <Project> Tasks
+
+## Overview
+<one paragraph: what this project is, current status, link to roadmap>
+
+## Current Phase: <phase name>
+### Active
+- [ ] **T-001** · <task title> — <status badge, e.g. 🔄 running> — <one-line context>
+- [ ] **T-002** · <task title> — 🔲 ready — <one-line context>
+- [ ] **T-003** · <task title> — 🚫 blocked — <one-line context, see reason>
+
+### Pending (queued, not yet started)
+- [ ] **T-004** · <task title> — <reason for queueing>
+
+### Completed This Phase
+- [x] **T-005** · <task title> — <one-line summary, link to wrap-up>
+- [x] **T-006** · <task title> — <one-line summary, link to wrap-up>
+
+## Next Phase: <phase name>
+<bullet list of tasks, not yet started>
+
+## Backlog / Future Phases
+<bullet list of tasks for phases beyond Next>
+
+## Completed (all phases, historical)
+- [x] **T-000** · <task title> — <phase X.Y, date, link to wrap-up>
+
+## Reference
+- Roadmap: `docs/roadmap-<proj>.md`
+- Kanban board: this file (TASKS.md)
+- Memory: memoryManager memory ids for session summaries
+```
+
+The "Current Phase" section is the **headline** of the file. It should be scannable in 30 seconds.
+
+## Operations
+
+### refresh_from_board()
+
+The default entry point. Reads the kanban board (TASKS.md kanban section or, if missing, the card-level format) and rebuilds the Current Phase section. The result is sorted: blocked → running → ready → pending.
+
+### mark_done(card_id, summary)
+
+Moves a card from Active to Completed This Phase. The summary is the worker's wrap-up closeout. The full wrap-up is in the kanban card; the todo list gets a one-liner plus a link to the card.
+
+### mark_blocked(card_id, reason)
+
+Moves a card from Active to a "Blocked" subsection with the reason. Stays visible (does not move to Pending) so the user sees it on every refresh.
+
+### add_discovered(item, source)
+
+Adds a new item that was discovered during the cycle. The source is a citation (e.g. "discovered during T-007: error handling for malformed messages was missing"). New items go to Active or Pending depending on whether they have dependencies.
+
+### drop(card_id, reason)
+
+Removes a card from the todo list entirely. Used for items that were discovered to be out of scope, duplicates, or absorbed into another card. The original card is moved to `archived` in the kanban board; the todo list entry is removed with a note in the changelog at the bottom of the file.
+
+### transition_to_next_phase()
+
+When the Current Phase is fully Done (all cards in `done` or `archived`), this operation:
+1. Renames the current section to "Completed (<phase name>)" with a date stamp
+2. Promotes Next Phase → Current Phase
+3. Promotes Backlog → Next Phase
+4. Stamps the new Current Phase header with today's date
+
+### sync_to_memory()
+
+Optional. Saves the current todo list to memoryManager with `project` metadata. The orchestrator does this on handoff. The skill does not run this automatically; it is invoked on demand.
+
+## Rules
+
+- **The todo list is a summary, not the source of truth.** The kanban board (TASKS.md kanban section) has the full card content. The todo list has scannable one-liners.
+- **Never duplicate content.** If a card's full details are in the kanban section, the todo list entry is a one-liner with a reference.
+- **The current phase is always at the top.** Historical completed phases are below.
+- **No "in progress" items that aren't being worked on.** If a card is `running` but no worker is active, the orchestrator must either re-claim it or move it to `blocked`.
+- **Use status badges** for scannability: 🔄 running, 🔲 ready, 🚫 blocked, ✅ done, 📦 archived, ❓ triage.
+
+## Anti-Patterns
+
+- **Do not** create todo items without a roadmap link (except for items discovered mid-cycle, which cite the source).
+- **Do not** keep items in the Active section that have been "stuck" for more than 7 days. They are stale; move them to Blocked with a reason.
+- **Do not** let the todo list grow unbounded. After 50+ items, archive the oldest 20% to a separate "Archive" file.
+- **Do not** rewrite the file from scratch each time. The updater should make targeted edits and preserve the structure.
+
+## Model
+
+Use **Gemini** for routine refreshes. Use a higher-reasoning model (e.g. `kimi-k2.6:cloud` for Boomerang) for `transition_to_next_phase` since that involves a structural reorganization.

package/.opencode/skills/update-gh-docs/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: update-gh-docs
+description: Updates GitHub-flavored documentation (README, CHANGELOG, release notes) so they are consistent, well-formatted, and validated to render correctly on github.com. Invoked as part of the release-card workflow, before tagging a release. Generic prompts for any GitHub-hosted project, with neuralgentics-specific tailoring (hero copy from Session 22, fish-shell user, podman-only, no docker, repo at Veedubin/neuralgentics).
+---
+
+# Update GitHub Docs
+
+## Description
+
+When the orchestrator is about to tag a release, this skill updates the GitHub-visible documentation files (`README.md`, `CHANGELOG.md`, GitHub release notes, and any repo-root `.md` files visitors see first) so they are:
+- **Consistent** — version numbers, dates, links all match
+- **Complete** — every public-facing file has accurate content
+- **Formatted correctly** — renders cleanly on github.com (no broken markdown, no mermaid — use Unicode box-drawing per neuralgentics house style)
+- **Validated** — links resolve, code blocks have correct language tags, table-of-contents works
+
+The skill is **generic by design** but with neuralgentics-specific tailoring at the bottom. It can be adapted to other projects by changing the project-specific block.
+
+## When to Use This Skill
+
+- The orchestrator is about to tag a release (`v*` tag push) and needs the public docs ready.
+- The user asks to "update the docs" or "make the README better."
+- A major new feature is shipped and the public-facing docs need an update.
+- The release-card workflow says `T-DOCS-NNN` is the next ready card.
+
+## Generic Flow (any GitHub project)
+
+### Step 1: Identify the docs to update
+Common files in order of visibility:
+1. `README.md` — the landing page visitors see first
+2. `CHANGELOG.md` — version history
+3. `docs/index.md` or similar — extended docs landing
+4. Any `ROADMAP.md`, `CONTRIBUTING.md`, `LICENSE` in repo root
+5. GitHub release notes (auto-generated from the tag push, but can be customized)
+
+### Step 1.5: Ensure external skills snapshot is fresh (release-time only)
+
+When tagging a release, the external skills snapshot must be bundled into the tarball so offline installs still get the curated set. The release script handles this automatically via `scripts/external-skills-fetcher.sh` (called from `release.sh` before `build_dist`).
+
+Verify the snapshot exists and is recent:
+- Check `~/.neuralgentics/external_skills/MANIFEST.json` exists
+- Check `MANIFEST.json` has entries for both `ai-research-skills` and `ui-ux-pro-max-skill`
+- Check the `commit_sha` fields are populated (not empty)
+
+If the snapshot is missing, run `./scripts/external-skills-fetcher.sh` to create it (or use `--skip-external-skills` to bundle a lean tarball without external skills).
+
+After build, verify `build/dist/share/external_skills/` contains:
+- `MANIFEST.json`
+- `ai-research-skills/` with at least one `SKILL.md`
+- `ui-ux-pro-max-skill/` with at least one `SKILL.md`
+- NO `.git/` directories
+
+### Step 2: Read each file and check
+- **Version numbers** — match the upcoming release tag (e.g., `v0.1.1`).
+- **Date stamps** — today's date in `YYYY-MM-DD` format.
+- **Code blocks** — every `\`\`\`` has a language tag (`\`\`\`bash`, `\`\`\`go`, `\`\`\`typescript`).
+- **Links** — relative links use folder-form (no `.md` extension — github.com resolves these automatically).
+- **Internal links** — broken anchors are the #1 GH-docs bug. Use `grep -rn "](#" .` to find anchors and verify they match headings.
+- **External links** — `curl -sIL <url>` to verify not 404.
+- **Mermaid** — replace with Unicode box-drawing per house style (or use `\`\`\`mermaid` blocks if the project wants them).
+- **Markdown flavor** — github.com uses GFM (GitHub Flavored Markdown). Tables, task lists, autolinks, strikethrough all work. HTML is allowed but discouraged.
+
+### Step 3: Update the changelog
+- Add a new top section for the new version.
+- Sections in this order: `Added`, `Changed`, `Fixed`, `Removed`, `Deprecated`, `Notes`.
+- Be specific — name the file, the function, the commit. Don't be vague.
+- Reference issue/PR numbers if they exist.
+- For a patch release (v0.1.0 → v0.1.1), the "Changed" section is usually empty.
+- For a minor release (v0.1.x → v0.2.0), the "Added" section is usually longest.
+
+### Step 4: Update the README
+- Verify the hero copy still matches the product reality.
+- Verify the install command actually works (curl the URL, verify the script exists).
+- Verify the "Quickstart" example actually runs end-to-end.
+- Verify all `[link](path)` references resolve.
+- Verify the badges (if any) point to live URLs.
+
+### Step 5: Validate on github.com (or local equivalent)
+- If you can push to a test branch, push and check the rendered page.
+- If not, use `markdownlint` or `markdown-link-check` if installed.
+- The minimum validation:
+  ```bash
+  # All internal .md links resolve
+  for f in $(find . -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/site/*"); do
+    grep -oE '\]\([^)]+\.md\)' "$f" | while read link; do
+      target=$(echo "$link" | sed 's/^](\(.*\))/\1/')
+      test -f "$target" || echo "BROKEN: $f -> $target"
+    done
+  done
+  ```
+- Manual check: open each file in a markdown preview (VS Code, Obsidian, etc.) and skim.
+
+### Step 6: Commit the docs updates
+- ONE commit per file (or one combined commit if all changes are small).
+- Message format: `docs(readme): update hero + install URL for v0.1.1 — Refs: T-DOCS-NNN`
+- Push to the same branch the release will tag from.
+
+## Neuralgentics-Specific Tailoring
+
+### House style (from Session 22)
+- **No mermaid diagrams in docs.** Use Unicode box-drawing characters (`┌─┐│└┘├┤┬┴┼─╭╮╰╯`). The user explicitly rejected mermaid.
+- **Hero copy is a flat feature list**, not clever marketing. Format:
+  > "Multi-Agent Orchestration, Permissions-based MCP Server Broker, Context Continuity Across Sessions"
+  Sub-headline: "An open-source agent runtime, built for engineers who ship."
+- **Honest comparison tables.** Cells with no data marked `(needs research)` rather than fabricated.
+- **No source builds for end users** — GH builds all release artifacts. The release workflow is at `.github/workflows/release.yml`.
+- **5 release targets only:** linux/amd64, linux/arm64, darwin/arm64 (Apple Silicon), windows/amd64, windows/arm64.
+
+### Project facts (verify before publishing)
+- **Repo URL:** `https://github.com/Veedubin/neuralgentics` (NOT `neuralgentics/neuralgentics` — that org does not exist).
+- **Latest tag:** check `git tag --sort=-version:refname | head -1` and `curl -s https://api.github.com/repos/Veedubin/neuralgentics/releases/latest | jq -r .tag_name`.
+- **Install command:**
+  ```bash
+  curl -fsSL https://raw.githubusercontent.com/Veedubin/neuralgentics/main/scripts/install.sh | bash
+  ```
+  (NOT `releases/latest/download/install.sh` — install.sh is not in release assets, it's served from `main`.)
+- **Container option:** `podman-compose up` (podman only, no docker).
+- **Test commands:**
+  - Go: `cd packages/<module> && GOWORK=off go test -short -timeout 60s ./...`
+  - TS: `cd packages/tui && bun test`
+- **5 platform builds:** linux-amd64, linux-arm64, darwin-arm64, windows-amd64, windows-arm64.
+
+### Files that MUST be updated per release (neuralgentics-specific)
+- `README.md` — install command, version badge, quickstart
+- `CHANGELOG.md` — new top section
+- `docs/index.md` — hero copy, latest features
+- `mkdocs.yml` — `site_url`, `repo_url`, version, any new pages
+- `package.json` — `version` field (root + `packages/tui`, `packages/opencode`)
+- `packages/backend-go/cmd/backend/main.go` — add `var version = ""` and assign to `serverInfo.Version` so ldflag works (TODO from v0.1.0)
+- `.github/workflows/release.yml` — verify Go version, build matrix, container job status
+
+### Files that MUST NOT be in the public repo
+- `HANDOFF.md`, `CONTEXT.md`, `TASKS.md` (gitignored, kept on disk for orchestrator state)
+- `certs/` (self-signed TLS, gitignored)
+- `.venv/`, `node_modules/`, `build/`, `dist/`, `site/` (build artifacts)
+- `opencode-base/` (legacy vendoring, removed in Session 21)
+- `docs/design/session-*.md` and `docs/design/*-plan*.md` (internal session artifacts, local-only)
+
+### Verifying the docs actually load
+- The mkdocs site is at `https://veedubin.github.io/neuralgentics/`. After pushing changes to `main`, the docs workflow (`.github/workflows/docs.yml`) re-deploys.
+- Validate: `curl -sIL https://veedubin.github.io/neuralgentics/ | head -5` (expect 200).
+- Validate: `curl -s https://veedubin.github.io/neuralgentics/getting-started/installation/ | grep -c "raw.githubusercontent"` (expect ≥1 — confirms the install URL fix from Session 22 is still in place).
+- Validate: open the GH release page after tagging and verify the rendered release notes look right.
+
+## Kanban Rule: Release Card MUST Spawn a T-DOCS Card
+
+Per AGENTS.md R6 (added Session 23): every release card (T-REL-NNN) MUST include a child `T-DOCS-NNN` card that invokes this skill before the tag is pushed. The release card is not "done" until the docs card is done.
+
+Release card template:
+
+```markdown
+### T-REL-001 · Tag v0.1.1 release
+- **Status:** ready
+- **Assignee:** boomerang-release
+- **Goal:** Tag v0.1.1 with all Session 23 bug fixes and push to GH.
+- **Acceptance:**
+  - [ ] All quality gates green (T-069 done)
+  - [ ] T-DOCS-XXX docs update done (invoke update-gh-docs skill)
+  - [ ] Tag v0.1.1 pushed to origin
+  - [ ] GH Actions release workflow green
+  - [ ] Release assets all uploaded (5 platforms + checksums.txt)
+  - [ ] Live docs site serves correctly
+- **Depends on:** T-069, T-DOCS-XXX
+- **Scope IN:** version bump, CHANGELOG, tag push, release verification
+- **Scope OUT:** code changes (those are separate cards)
+```
+
+The T-DOCS-XXX card:
+
+```markdown
+### T-DOCS-001 · Update GitHub docs for v0.1.1
+- **Status:** ready
+- **Assignee:** boomerang-writer
+- **Skill:** update-gh-docs
+- **Goal:** Update README, CHANGELOG, docs/index.md, mkdocs.yml, package.json versions for v0.1.1.
+- **Acceptance:**
+  - [ ] All version numbers match v0.1.1
+  - [ ] All internal links resolve
+  - [ ] Hero copy still accurate
+  - [ ] Install command still works (curl-tested)
+  - [ ] Hero copy is the flat feature list (not clever marketing)
+  - [ ] No mermaid in any doc file
+  - [ ] One commit per file
+- **Depends on:** T-REL-001 (for version target)
+```
+
+## Anti-Patterns
+
+- **Don't** auto-generate docs from code. They're for humans. Use code for the data, write the prose.
+- **Don't** put `WIP` or `TODO` in public docs. Either finish it or don't include it.
+- **Don't** link to local files with `.md` extensions — github.com doesn't render these as anchors. Use folder-form: `[link](path/to/page/)` not `[link](path/to/page.md)`.
+- **Don't** include comparison cells with fabricated data. Mark `(needs research)` instead.
+- **Don't** update docs in the same commit as code changes. Separate them for clean rollback.
+- **Don't** push docs changes directly to main. Open a PR unless the project is single-maintainer and that's the norm.
+- **Don't** add emojis to docs unless the user explicitly asks. (User preference: no emojis in docs.)
+
+## Model
+
+Use **Gemma** for routine doc updates (formatting, link checks, version bumps). Use **DeepSeek** for any doc that requires careful judgment (hero copy, comparison tables, hero sections).
+
+## Owner
+
+- `boomerang-writer` is the primary agent for this skill.
+- The orchestrator invokes it as part of the release-card workflow.
+- The skill can also be invoked manually when the user says "update the docs" or "/boomerang-handoff" if a release is imminent.
+
+*(Added 2026-06-05 Session 23. Prior to this, doc updates were ad-hoc. This skill formalizes the checklist and ties it to the release-card workflow so docs are NEVER out of sync with the code at tag time.)*

package/dist/neuralgentics/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/neuralgentics/init.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/neuralgentics/init.ts"],"names":[],"mappings":"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"}