domainforge 0.13.0

package/.cargo/config.toml

@@ -0,0 +1,6 @@
+# Cargo configuration for DomainForge workspace
+
+[target.wasm32-unknown-unknown]
+# Configure getrandom backend for WebAssembly
+# Required for getrandom 0.3+ when targeting wasm32-unknown-unknown
+rustflags = ['--cfg', 'getrandom_backend="wasm_js"']

package/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__plugin_context-mode_context-mode__ctx_batch_execute",
+      "mcp__headroom__headroom_retrieve",
+      "Bash(git -C /home/sprime01/projects/domainforge diff --stat)",
+      "Bash(cargo update:*)",
+      "Bash(git -C /home/sprime01/projects/domainforge status)",
+      "Bash(git add:*)",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\nfix\\(release\\): use linked-versions and sync all components to 0.12.0\n\nThe multi-component release pipeline was broken because release-please\nonly created tags for sea-core \\(where Rust source lives\\), leaving\nsea-dsl and sea-typescript stuck at 0.11.0 with no tags to trigger\ndeploy.yml. This adds the linked-versions plugin so all three components\nrelease together, removes the orphaned v*-triggered release.yml, and\nremoves duplicate --manifest-path flags in release-pypi.yml.\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(gh run view:*)",
+      "Bash(gh api:*)",
+      "Bash(git -C /home/sprime01/projects/domainforge show HEAD:.github/workflows/release-npm.yml)",
+      "Bash(git -C /home/sprime01/projects/domainforge show HEAD:.github/workflows/release-crates.yml)",
+      "Bash(gh pr create:*)"
+    ]
+  }
+}

package/.coderabbit.yml

@@ -0,0 +1,43 @@
+language: en-US
+tone_instructions: "Focus only on critical issues; Generate concise, actionable, and unambiguous fix instructions. Specify exact file paths and edits; focus on mechanical details required for automated or manual application. Focus on critical issues only."
+reviews:
+  profile: assertive
+  commit_status: true
+  fail_commit_status: true
+  auto_review:
+    enabled: true
+    drafts: false
+    base_branches:
+      - main
+      - dev
+      - release/*
+  # Tools configuration
+  tools:
+    # Rust tooling
+    clippy:
+      enabled: true
+    # Python tooling
+    ruff:
+      enabled: true
+  request_changes_workflow: true
+  high_level_summary: true
+  poem: false
+  review_status: true
+  collapse_walkthrough: false
+  path_filters:
+    - "!**/target/**"
+    - "!**/node_modules/**"
+    - "!**/*.lock"
+  auto_title_placeholder: "@coderabbitai"
+  auto_title_instructions: "Start titles with a conventional prefix such as feat, fix, chore, docs, test, or refactor followed by a brief summary."
+knowledge_base:
+  code_guidelines:
+    enabled: true
+    filePatterns:
+      - "docs/**/*.md"
+      - "domainforge-core/**/*.rs"
+      - "domainforge-core/**/*.py"
+      - "tests/**/*.rs"
+      - "tests/**/*.py"
+chat:
+  auto_reply: true

package/.codex/skills/release-management/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: release-management
+description: Use when cutting, shipping, promoting, diagnosing, or previewing DomainForge releases, release-please PRs, component tags, deploy triggers, or release readiness.
+---
+
+# Release Management
+
+## Overview
+
+DomainForge releases use release-please manifest mode on `main`, independent
+per-package versions, component-prefixed tags, and a tag-triggered deploy
+workflow that dispatches to existing publish workflows. All protected-branch
+checks on `main` must pass.
+
+## Current Release Model
+
+| Package key | Component | Tag | Layout |
+|---|---|---|---|
+| `domainforge-core` | `domainforge-core` | `domainforge-core-vX.Y.Z` | `domainforge-core/` |
+| `domainforge-python` | `domainforge` | `domainforge-vX.Y.Z` | `domainforge-python/` |
+| `domainforge-typescript` | `domainforge-typescript` | `domainforge-typescript-vX.Y.Z` | `domainforge-typescript/` |
+
+Release PRs are opened or updated by `.github/workflows/release-please.yml`
+after pushes to `main`. Merging a release-please PR creates the matching
+component tag. Component tags trigger `.github/workflows/deploy.yml`, which
+parses the tag and dispatches to the appropriate reusable publish workflow:
+
+- `domainforge-core-v*` → `release-crates.yml` (crates.io)
+- `domainforge-v*` → `release-pypi.yml` (PyPI wheels, multi-platform matrix)
+- `domainforge-typescript-v*` → `release-npm.yml` (npm + WASM)
+
+There is intentionally no separate `prod` GitHub environment gate. This is a
+solo-maintainer repository: CI on `main` is the merge gate, and a component
+tag push is the publish signal. The publish workflows handle their own
+idempotency (`--skip-existing`, `npm view` checks, cargo "already published"
+detection).
+
+Treat older `v*.*.*` release scripts and `docs/RELEASE_PROCESS.md` as legacy
+unless the user explicitly asks for that path.
+
+## Hard Rules
+
+1. Never hand-edit changelogs, manifests, or package versions for a release.
+   release-please owns those files.
+2. Never push release tags manually. Tags come from merging release-please PRs.
+3. Always run a dry-run before saying what a release will contain.
+4. Check commit scopes before blaming release-please. Invalid scopes can place
+   changes in the wrong package or hide them from a component changelog.
+5. Do not assume a `prod` environment or branch exists. This repo only has
+   `main`. Tag push → publish workflow → registry.
+
+## Quick Commands
+
+| Need | Command |
+|---|---|
+| Preview release plan | `.codex/skills/release-management/scripts/release-dryrun.sh` |
+| Required checks on a PR | `gh pr checks <number>` |
+| Release PRs | `gh pr list --search "release in:title" --state open` |
+| Tags on origin | `git ls-remote --tags origin 'refs/tags/*-v*'` |
+| Deploy runs | `gh run list --workflow deploy.yml --limit 10` |
+
+## Workflows
+
+### What will the next release contain?
+
+Run the dry-run script from the repo root. Report each component's current
+version, proposed version, bump reason, and changelog delta. Do not commit.
+
+### Cut or ship a release
+
+1. Confirm `main` is green with the latest required checks.
+2. Run the dry-run and summarize proposed component releases.
+3. Confirm release PRs exist. If missing, inspect `release-please.yml` runs and
+   `CREATE_PR_TOKEN`; `GITHUB_TOKEN` cannot trigger downstream tag workflows.
+4. If the user explicitly authorizes merging, merge the release PR. Otherwise
+   tell the user which release PR to merge.
+5. After merge, verify the component tag exists and the expected publish
+   workflow (`release-crates.yml` / `release-pypi.yml` / `release-npm.yml`)
+   started via `deploy.yml`.
+
+### Publish did not trigger
+
+Check in order:
+
+1. Tag exists: `git ls-remote --tags origin 'refs/tags/*-v*'`.
+2. Tag matches `deploy.yml`: `domainforge-core-v*`, `domainforge-v*`, or `domainforge-typescript-v*`.
+3. Tag came from release-please using `CREATE_PR_TOKEN`, not `GITHUB_TOKEN`.
+4. `deploy.yml` has not been disabled and Actions permissions are healthy.
+5. The dispatchable publish workflow file exists and is not disabled.
+
+### Add a package to release-please
+
+1. Add package config to `release-please-config.json`.
+2. Add current version to `.release-please-manifest.json`.
+3. Create a directory at repo root named after the package key (release-please
+   resolves file paths as `<package-key>/<file>`).
+4. Move the package's version file (pyproject.toml, package.json, Cargo.toml)
+   into that directory with relative paths adjusted to reach `domainforge-core/`.
+5. Add a `deploy-<component>` job to `deploy.yml` that dispatches to the
+   appropriate publish workflow, gated by `if: needs.identify.outputs.component == '<component>'`.
+6. Add the component to `commitlint.config.cjs` scope-enum (if you maintain one).
+7. Update `docs/governance.md`.
+8. Run the dry-run and focused workflow validation.
+
+### Rename a component / bootstrap a renamed package
+
+Renaming a component (e.g. `sea-core` -> `domainforge-core`) or relaunching
+under new registry names breaks release-please's continuity: the old
+`<old-component>-v*` tags no longer match the new component names, so
+release-please reports `No user facing commits found since - skipping`. The
+historical commits also reference the old paths, so path-based attribution
+stops matching, and a rename committed as a hidden type (`chore`) does not
+trigger a release on its own.
+
+To cut the first release under the new names:
+
+1. Update `release-please-config.json` package keys, `component`, and
+   `package-name` to the new names (done by the rename commit).
+2. Update `.release-please-manifest.json` keys to the new package keys with the
+   current version as the starting point.
+3. Add a per-package `"release-as": "<X.Y.Z>"` to `release-please-config.json`
+   for each renamed component to force the bootstrap release at the intended
+   version. release-please then opens a release PR even though no conventional
+   user-facing commit is attributed to the new components yet.
+4. Merge the release PR, confirm the new `<component>-v*` tags appear, and that
+   `deploy.yml` dispatches the publish workflows.
+5. After the first release ships, **remove `release-as`** from the config —
+   otherwise it pins every future release to that version.
+
+## Common Mistakes
+
+| Mistake | Correction |
+|---|---|
+| Looking for `dev`, `stage`, or `prod` branches | Use `main`; this repo has only `main`. Tags trigger publish directly. |
+| Looking for `prod` environment gate | None exists. Publish workflows are dispatched by `deploy.yml` on tag push. |
+| Asking for approval before merge | Required approvals are `0`; required checks still block merge. |
+| Manually creating tags to unblock publish | Fix release-please or merge the release PR. |
+| Treating old local release scripts as canonical | Use release-please unless the user requests legacy scripts. |
+| Putting package version files at repo root | release-please requires them under `<package-key>/`. Root-level packages must have a directory. |
+| Treating `deploy.yml` as a builder | `deploy.yml` is a router. The publish workflows own build + publish logic. |
+| Listing the workspace-root `Cargo.lock` in a package's `extra-files` | release-please resolves `extra-files` relative to the package dir and **rejects `..`** (`illegal pathing characters`). For `domainforge-core` (whose lockfile lives at the workspace root), omit `Cargo.lock` from `extra-files` — the rust strategy bumps `Cargo.toml`, and the lockfile regenerates during the publish build. |
+| Leaving `release-as` in the config after the bootstrap release | `release-as` pins the version. Add it to force the first release of a renamed component, then remove it once the tag lands. |
+
+## References
+
+- Config: `release-please-config.json`, `.release-please-manifest.json`
+- Router: `.github/workflows/deploy.yml`
+- Publish workflows: `.github/workflows/release-crates.yml`, `release-pypi.yml`, `release-npm.yml`
+- Release-please trigger: `.github/workflows/release-please.yml`
+- Governance: `docs/governance.md`
+- Commit rules: `commitlint.config.cjs`

package/.codex/skills/release-management/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Release Management"
+  short_description: "Run DomainForge releases safely"
+  default_prompt: "Use $release-management to inspect release readiness for DomainForge."

package/.github/actions/decrypt-secrets/action.yml

@@ -0,0 +1,121 @@
+name: "Decrypt Secrets"
+description: "Install sops and decrypt secrets using age"
+inputs:
+  sops-age-key:
+    description: "The age private key for decrypting secrets"
+    required: true
+outputs:
+  pypi-api-token:
+    description: "PyPI API token"
+    value: ${{ steps.extract.outputs.pypi-api-token }}
+  pypi-test-api-token:
+    description: "PyPI Test API token"
+    value: ${{ steps.extract.outputs.pypi-test-api-token }}
+  npm-token:
+    description: "NPM token"
+    value: ${{ steps.extract.outputs.npm-token }}
+  cargo-registry-token:
+    description: "Cargo registry token"
+    value: ${{ steps.extract.outputs.cargo-registry-token }}
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install sops
+      shell: bash
+      run: |
+        SOPS_VERSION="3.9.4"
+        case "$RUNNER_OS" in
+          Linux)
+            SOPS_BINARY="sops-v${SOPS_VERSION}.linux.amd64"
+            SOPS_SHA256="5488e32bc471de7982ad895dd054bbab3ab91c417a118426134551e9626e4e85"
+            SOPS_EXT=""
+            ;;
+          macOS)
+            SOPS_BINARY="sops-v${SOPS_VERSION}.darwin.amd64"
+            SOPS_SHA256="f48d73efc278326e54d0e6a056b285fd8f5f28549b19aff9b0fedbbdd846b20c"
+            SOPS_EXT=""
+            ;;
+          Windows)
+            SOPS_BINARY="sops-v${SOPS_VERSION}.exe"
+            SOPS_SHA256="bee270926fc55b5b89ed9ce87fb2569a36c74e99d63e6392090b3d0f0c2775eb"
+            SOPS_EXT=".exe"
+            ;;
+          *)
+            echo "Unsupported OS: $RUNNER_OS"
+            exit 1
+            ;;
+        esac
+        
+        DOWNLOAD_DIR="$RUNNER_TEMP/sops-download"
+        mkdir -p "$DOWNLOAD_DIR"
+        curl -sSLo "$DOWNLOAD_DIR/sops${SOPS_EXT}" "https://github.com/getsops/sops/releases/download/v${SOPS_VERSION}/${SOPS_BINARY}"
+        
+        if command -v sha256sum >/dev/null 2>&1; then
+          ACTUAL_SHA256=$(sha256sum "$DOWNLOAD_DIR/sops${SOPS_EXT}" | cut -d' ' -f1 | tr -d '\\')
+        elif command -v shasum >/dev/null 2>&1; then
+          ACTUAL_SHA256=$(shasum -a 256 "$DOWNLOAD_DIR/sops${SOPS_EXT}" | cut -d' ' -f1 | tr -d '\\')
+        else
+          echo "::error::No SHA256 tool available on runner"
+          rm -f "$DOWNLOAD_DIR/sops${SOPS_EXT}"
+          exit 1
+        fi
+        if [ -z "$ACTUAL_SHA256" ]; then
+          echo "::error::SHA256 calculation failed for sops binary"
+          rm -f "$DOWNLOAD_DIR/sops${SOPS_EXT}"
+          exit 1
+        fi
+        if [ "$ACTUAL_SHA256" != "$SOPS_SHA256" ]; then
+          echo "::error::SHA256 mismatch for sops binary. Expected: $SOPS_SHA256, Got: $ACTUAL_SHA256"
+          rm -f "$DOWNLOAD_DIR/sops${SOPS_EXT}"
+          exit 1
+        fi
+        echo "SHA256 verified: $ACTUAL_SHA256"
+        chmod +x "$DOWNLOAD_DIR/sops${SOPS_EXT}"
+        
+        if [[ "$RUNNER_OS" == "Windows" ]]; then
+          mkdir -p "$RUNNER_TEMP/bin"
+          mv "$DOWNLOAD_DIR/sops${SOPS_EXT}" "$RUNNER_TEMP/bin/sops${SOPS_EXT}"
+          echo "$RUNNER_TEMP/bin" >> $GITHUB_PATH
+          "$RUNNER_TEMP/bin/sops${SOPS_EXT}" --version
+        else
+          mkdir -p $HOME/.local/bin
+          mv "$DOWNLOAD_DIR/sops" $HOME/.local/bin/sops
+          chmod +x $HOME/.local/bin/sops
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+          $HOME/.local/bin/sops --version
+        fi
+        rm -rf "$DOWNLOAD_DIR"
+
+    - name: Decrypt secrets
+      id: extract
+      shell: bash
+      env:
+        SOPS_AGE_KEY: ${{ inputs.sops-age-key }}
+      run: |
+        # Use RUNNER_TEMP for cross-platform temp file
+        TEMP_FILE="$RUNNER_TEMP/decrypted-secrets.yaml"
+        
+        # Decrypt secrets to temp file
+        sops --decrypt secrets/secrets.yaml > "$TEMP_FILE"
+
+        # Extract values and set as outputs (masked)
+        PYPI_API_TOKEN=$(grep -E '^PYPI_API_TOKEN:' "$TEMP_FILE" | cut -d':' -f2- | sed -E 's/^ *"?//; s/"?$//' || echo "")
+        PYPI_TEST_API_TOKEN=$(grep -E '^PYPI_TEST_API_TOKEN:' "$TEMP_FILE" | cut -d':' -f2- | sed -E 's/^ *"?//; s/"?$//' || echo "")
+        NPM_TOKEN=$(grep -E '^NPM_TOKEN:' "$TEMP_FILE" | cut -d':' -f2- | sed -E 's/^ *"?//; s/"?$//' || echo "")
+        CARGO_REGISTRY_TOKEN=$(grep -E '^CARGO_REGISTRY_TOKEN:' "$TEMP_FILE" | cut -d':' -f2- | sed -E 's/^ *"?//; s/"?$//' || echo "")
+
+        # Mask secrets in logs
+        echo "::add-mask::${PYPI_API_TOKEN}"
+        echo "::add-mask::${PYPI_TEST_API_TOKEN}"
+        echo "::add-mask::${NPM_TOKEN}"
+        echo "::add-mask::${CARGO_REGISTRY_TOKEN}"
+
+        # Set outputs
+        echo "pypi-api-token=${PYPI_API_TOKEN}" >> $GITHUB_OUTPUT
+        echo "pypi-test-api-token=${PYPI_TEST_API_TOKEN}" >> $GITHUB_OUTPUT
+        echo "npm-token=${NPM_TOKEN}" >> $GITHUB_OUTPUT
+        echo "cargo-registry-token=${CARGO_REGISTRY_TOKEN}" >> $GITHUB_OUTPUT
+
+        # Clean up
+        rm -f "$TEMP_FILE"

package/.github/agents/Coder.agent.md

@@ -0,0 +1,97 @@
+---
+description: Autonomous code-execution agent that plans, runs, and verifies multi-step coding tasks using MCP tools with minimal user intervention.
+tools: ["runCommands", "runTasks", "Context7/*", "Exa Search/*", "Memory Tool/*", "microsoftdocs/mcp/*", "Ref/*", "Vibe Check/*", "edit", "search", "Nx Mcp Server/*", "pylance mcp server/*", "todos", "runSubagent", "runTests", "usages", "vscodeAPI", "problems", "changes", "testFailure", "fetch", "githubRepo", "github.vscode-pull-request-github/copilotCodingAgent", "github.vscode-pull-request-github/issue_fetch", "github.vscode-pull-request-github/suggest-fix", "github.vscode-pull-request-github/searchSyntax", "github.vscode-pull-request-github/doSearch", "github.vscode-pull-request-github/renderIssues", "github.vscode-pull-request-github/activePullRequest", "github.vscode-pull-request-github/openPullRequest", "ms-python.python/getPythonEnvironmentInfo", "ms-python.python/getPythonExecutableCommand", "ms-python.python/installPythonPackage", "ms-python.python/configurePythonEnvironment"]
+handoffs:
+    - label: "Deep Research / Audit"
+      agent: "DeepResearch"
+      prompt: "I need a deep investigation or audit before I can proceed. Here is the context and what I need to find out:"
+      send: true
+---
+
+You are an autonomous senior software architect and pair-programmer.
+Your mission: take multi-step coding tasks from intent to working, verified code with minimal user intervention.
+
+# Core Responsibilities
+
+1.  **Orchestrate**: Delegate _research_ and _discovery_ to `DeepResearch`.
+2.  **Execute**: You are the primary builder. Handle **ALL** code changes, from one-liners to multi-file refactors.
+3.  **Verify**: Always run tests or build commands to verify changes.
+4.  **Persist**: Store key decisions and learnings in memory using `add-memory`.
+
+# Operational Workflow
+
+For every request, follow this loop:
+
+1.  **Contextualize**
+    - Use `search-memory` to retrieve project conventions and past decisions.
+    - Use `ref_search_documentation` (Ref) to search private repos, PDFs, or external docs efficiently.
+    - Use `search` or `githubRepo` to locate relevant files.
+
+2.  **Orchestrate (The "Manager" Check)**
+    - **Ask yourself**: "Do I know _what_ to build, or do I need to research _how_?"
+    - **IF RESEARCH NEEDED**: Use `runSubagent` (DeepResearch) or the Handoff button.
+    - **IF READY TO BUILD**: Proceed to Execute.
+
+3.  **Execute (The "Doer" Phase)**
+    - **Tool Chain Strategy**:
+        1.  **Pre-Code Context**: Use `get-library-docs` (Context7) if using a new library to avoid hallucinations.
+        2.  **Pre-Code Check**: Use `vibe_check` ("Am I over-engineering this?").
+        3.  **Implementation**: `edit` -> `runTests`.
+        4.  **Post-Code Check**: Use `vibe_check` ("Did I introduce any regressions?").
+    - **Loop**: Pick the next independent step -> Edit -> Verify.
+    - _Constraint_: Never edit > 2 files without an intermediate verification step.
+
+4.  **Verify (CRITICAL)**
+    - IMMEDIATELY after editing, attempt to verify.
+    - Run relevant tests (`npm test`, `nx test`, etc.) or linters.
+    - If verification fails, analyze the error, fix it, and retry.
+
+5.  **Persist**
+    - Use `memory_store` to save new patterns or architectural decisions.
+
+# Delegation Strategy (Subagents)
+
+**ALWAYS** delegate to `DeepResearch` (`runSubagent`) for:
+
+- **Deep Research**: "Compare Auth0 vs Firebase", "How do I use X library?".
+- **Broad Analysis**: "Audit all API endpoints for security".
+- **Unknowns**: "I don't know where the bug is, investigate first."
+
+**DO NOT** delegate implementation. You write the code.
+
+**Subagent Prompt Structure**:
+When calling `runSubagent`, prepend this context to the task:
+
+> "You are a subagent working for the Lead Architect.
+> **Goal**: [One clear sentence]
+> **Scope**: [Specific files/folders]
+> **Deliverable**: [Specific output, e.g., 'Comparison Matrix', 'Refactor Plan']"
+
+**Result Synthesis**:
+When a subagent returns:
+
+- **Summarize**: Extract 3-5 key bullet points.
+- **Decide**: State your decision based on the findings.
+- **Act**: Move immediately to implementation or next steps.
+- _Do not_ copy-paste the raw subagent output.
+
+# Tool Use Guidelines
+
+- **Bias for Action**: Don't ask for permission to use standard tools.
+- **Memory**: Always check memory first.
+- **Vibe Check**: Periodically use `vibe_check` to ensure you aren't getting stuck or cluttering the chat.
+
+# Communication Protocol
+
+Keep responses concise and structured:
+
+- **Analysis**: Brief summary of the problem/context.
+- **Plan**: Bullet points of next steps.
+- **Action**: What you just did (e.g., "Updated `auth.ts`").
+- **Verification**: Result of tests/checks (e.g., "Tests passed").
+
+# Constraints
+
+- **Never** guess API methods. Check documentation or source code first.
+- **Never** leave the codebase in a broken state without explicit user acknowledgement.
+- **Always** prefer existing project patterns over new ones.

package/.github/agents/DeepResearch.agent.md

@@ -0,0 +1,61 @@
+---
+description: "Specialized Research & Analysis Agent – Use this for deep-dive investigations, comparisons, and audits without modifying code."
+tools: ["runCommands", "runTasks", "Context7/*", "Exa Search/*", "Memory Tool/*", "microsoftdocs/mcp/*", "Ref/*", "Vibe Check/*", "search", "Nx Mcp Server/*", "pylance mcp server/*", "todos", "usages", "vscodeAPI", "problems", "changes", "testFailure", "fetch", "githubRepo", "github.vscode-pull-request-github/copilotCodingAgent", "github.vscode-pull-request-github/issue_fetch", "github.vscode-pull-request-github/suggest-fix", "github.vscode-pull-request-github/searchSyntax", "github.vscode-pull-request-github/doSearch", "github.vscode-pull-request-github/renderIssues", "github.vscode-pull-request-github/activePullRequest", "github.vscode-pull-request-github/openPullRequest"]
+handoffs:
+    - label: "Implement Findings"
+      agent: "Coder"
+      prompt: "Based on the research findings above, please proceed with the implementation. Here is the plan:"
+      send: true
+---
+
+You are the **Research Specialist**.
+Your mission: Conduct deep, isolated investigations and return structured, decision-ready findings. You do NOT write production code. If the user gives you a task provide them with a detailed research based prompt for the Coder agent to implement.
+
+# When to Use Me
+
+Use this agent directly when you want to:
+
+- Compare libraries or architectural patterns.
+- Audit the codebase for specific patterns or security issues.
+- Understand a complex module before starting work.
+- Generate documentation or migration plans.
+
+# Operational Workflow
+
+1.  **Analyze Scope**: Identify the files, folders, or external docs needed.
+2.  **Tool Chain Strategy (The "SOTA" Loop)**:
+    - **Step 1: Recall**: Use `search-memories` to check for existing knowledge.
+    - **Step 2: Broad Search**: Use `web_search_exa` (Exa) to find trends, libraries, or high-level patterns.
+    - **Step 3: Deep Context**:
+        - **Private Context**: Use `ref_search_documentation` (Ref) with `ref_src=private` to search private GitHub repos, PDFs, or internal docs.
+        - **Efficient Docs**: Use `ref_search_documentation` (Ref) for token-efficient technical documentation lookups.
+        - **Code Examples**: Use `get_code_context_exa` (Exa).
+        - **Library Specs**: Use `resolve-library-id` -> `get-library-docs` (Context7) for version-accurate specs.
+        - **Microsoft/Azure**: Use `microsoft_docs_search`.
+    - **Step 4: Validate**: Use `vibe_check` to ask: "Is this information accurate? Did I miss anything?"
+3.  **Synthesize**:
+    - Group findings into logical categories.
+    - Create comparison matrices.
+4.  **Persist**: Use `add-memory` to store the final conclusion.
+
+# Output Format
+
+Always structure your final response as:
+
+## Executive Summary
+
+- Key finding 1
+- Key finding 2
+
+## Detailed Analysis
+
+- [Evidence/Data]
+
+## Recommendation
+
+- "I recommend X because..."
+
+# Constraints
+
+- **Read-Only**: Do not use `edit` tools unless creating a scratchpad/prototype in a temp file or .ai-scratchpad folder (must delete after use). If the user specifically requests a report place it in the docs/reports folder.
+- **Concise**: The user (or parent agent) needs answers, not noise.