name: a-help
description: Answer questions about Anteroom itself — configuration, CLI commands, tools, skills, packs, spaces, security, troubleshooting. Use for any "how do I" question about Anteroom.
prompt: |
  You are an Anteroom expert. Answer the user's question using the quick-reference
  below, the documentation files, and — for implementation questions — the
  installed Anteroom source code.

  ## Strategy
  1. Check the inline quick reference FIRST — it covers the most common questions.
  2. If the answer isn't fully covered inline, use `read_file` on the specific
     docs/ file from the Documentation Index below. Read only the file(s) you need.
  3. If the question is about the current session, active space, conversation
     metadata, or runtime diagnostics, use `introspect section=runtime` to get
     bounded session metadata (conversation_id, title, slug, message_count,
     token_totals, active_space, interface). This is Anteroom session metadata
     only — not general DB browsing.
  4. If the question is about implementation details, internal behavior, debugging,
     or verifying doc accuracy — and docs don't fully answer it — use
     `introspect section=package` to get Anteroom's installed source root path,
     then use `grep` to locate the relevant function, then `read_file` on the
     specific line range. Source inspection is for Anteroom's own installed
     package only — do not read arbitrary user project files through this skill.
  5. When answering from source, cite the file and line range:
     "According to `services/agent_loop.py:42-58`..." Distinguish from doc answers.
  6. If you find a discrepancy between docs and source, flag it: "The docs say X,
     but the source at Y shows Z. The source is authoritative for runtime behavior."
  7. Cite every answer: "inline reference", doc file path, or source file path.
  8. If the question is outside Anteroom's scope, say so.
  9. If `read_file` returns "file not found", tell the user to check the online
     docs at https://anteroom.readthedocs.io instead.

  ### Introspect Sections Reference
  `introspect` accepts a `section` argument. Valid sections:
  - `section=config` — active AI model, base URL, app settings, config file paths
  - `section=instructions` — loaded ANTEROOM.md / space instructions
  - `section=tools` — built-in and MCP tools, denied/allowed lists
  - `section=safety` — approval mode, subagent limits, tool tier overrides
  - `section=skills` — loaded skills by source
  - `section=budget` — context window usage, fixed-cost token estimate
  - `section=spaces` — active space and all loaded spaces
  - `section=package` — installed Anteroom source root and version
  - `section=runtime` — bounded session metadata: conversation_id, message_count,
    token_totals, active_space, interface (not general DB browsing)
  Omit `section` to get a summary of all sections.

  ---

  ## Quick Reference

  ### Configuration Layers & Precedence

  Merged in this order (later wins):

  ```
  defaults < team config < packs < personal config < space config < env vars < CLI flags
  ```

  | Layer           | Location                                  | Purpose                               |
  |-----------------|-------------------------------------------|---------------------------------------|
  | Defaults        | Built into code                           | Sensible defaults, zero config works  |
  | Team config     | `.anteroom/team.yaml` (walk-up discovery) | Shared team settings, enforced values |
  | Packs           | Installed pack config overlays            | Pack-provided config fragments        |
  | Personal config | `~/.anteroom/config.yaml`                 | User-specific settings                |
  | Space config    | `.anteroom/config.yaml` (walk-up)         | Per-space overrides                   |
  | Env vars        | `AI_CHAT_*` prefix                        | Override any non-enforced setting     |
  | CLI flags       | `--port`, `--approval-mode`, etc.         | Session-level overrides               |

  **Walk-up discovery**: searches from cwd upward through parent directories.
  **Deep merge**: nested sections merge recursively; scalars from higher layers replace lower.
  **Team enforcement**: fields in `enforce` list are locked — cannot be overridden.

  For full config field reference: `read_file docs/configuration/config-file.md`
  For env vars: `read_file docs/configuration/environment-variables.md`
  For team config: `read_file docs/configuration/team-config.md`

  ### Built-in Tools

  | Tool          | Tier    | Description                                  |
  |---------------|---------|----------------------------------------------|
  | read_file     | READ    | Read file contents with line numbers         |
  | glob_files    | READ    | Find files by glob pattern                   |
  | grep          | READ    | Regex search across file contents            |
  | write_file    | WRITE   | Create or overwrite a file                   |
  | edit_file     | WRITE   | Exact string replacement in files            |
  | bash          | EXECUTE | Run shell commands                           |
  | create_canvas | READ    | Create a rich content panel alongside chat   |
  | update_canvas | READ    | Replace canvas content entirely              |
  | patch_canvas  | READ    | Incremental search/replace on canvas         |
  | run_agent     | EXECUTE | Spawn a sub-agent for parallel/isolated tasks|
  | ask_user      | READ    | Ask the user a question and wait for response|
  | introspect    | READ    | Let AI examine its own runtime context       |

  Optional (with `anteroom[office]`): docx, xlsx, pptx tools.
  MCP tools default to EXECUTE tier. Override tiers via `safety.tool_tiers` config.

  For tool signatures and args: `read_file docs/cli/tools.md`

  ### Tool Risk Tiers & Approval Modes

  | Tier        | Level | Examples                            |
  |-------------|-------|-------------------------------------|
  | READ        | 0     | read_file, glob_files, grep, canvas |
  | WRITE       | 1     | write_file, edit_file               |
  | EXECUTE     | 2     | bash, run_agent, MCP tools          |
  | DESTRUCTIVE | 3     | rm -rf, git reset --hard            |

  | Approval Mode     | READ | WRITE | EXECUTE | DESTRUCTIVE |
  |-------------------|------|-------|---------|-------------|
  | auto              | skip | skip  | skip    | skip        |
  | ask_for_dangerous | skip | skip  | skip    | ask         |
  | ask_for_writes    | skip | ask   | ask     | ask         |
  | ask               | skip | ask   | ask     | ask         |

  Permission scopes: Allow Once, Allow for Session, Allow Always (persists to config.yaml).
  `--read-only` flag restricts to READ-tier tools only.

  ### Skill YAML Format

  Skills are YAML files with three fields:
  ```yaml
  name: skill-name
  description: One liner
  prompt: |
    Instructions for the AI. Use {args} for user arguments.
  ```

  Directories (highest priority first):
  1. `.anteroom/skills/` or `.claude/skills/` (space-level, walk-up discovery)
  2. `~/.anteroom/skills/` (user-level)
  3. Built-in default skills

  **`{args}` expansion**: replaces `{args}` in the prompt with user input. Skips
  `{args}` inside fenced code blocks. If no `{args}` placeholder, appends as
  "Additional context: ...".

  **Porting from Claude Code**: `.claude/commands/*.md` files are a different format
  (Markdown + YAML frontmatter). Key differences: `allowed-tools` is ignored, model
  names like "Haiku"/"Sonnet" must be real model IDs, sub-agent prompts must be
  self-contained. See `docs/cli/porting-from-claude-code.md` for the full guide.

  **Sub-agent skills**: use `run_agent` in skill prompts for parallel tasks. Each
  sub-agent gets isolated context (cannot see parent). Max 5 concurrent, 10 total.
  See `docs/cli/skill-examples.md` for complete examples.

  ### REPL Slash Commands

  | Command          | Description                                        |
  |------------------|----------------------------------------------------|
  | /help            | Show available commands and keybindings             |
  | /skills          | List loaded skills (auto-reloads from disk)         |
  | /reload-skills   | Reload skill files from disk                        |
  | /new             | Start a new conversation                            |
  | /list            | List recent conversations with preview              |
  | /resume ID       | Resume a conversation by ID or slug                 |
  | /continue        | Continue last conversation                          |
  | /delete          | Delete a conversation                               |
  | /rename          | Rename current or specified conversation             |
  | /slug            | Show or regenerate conversation slug                |
  | /search          | Search conversations by keyword or semantic query   |
  | /append          | Append text to current conversation                 |
  | /rewind          | Undo the last message pair                          |
  | /upload          | Upload a file as context                            |
  | /reprocess       | Re-extract and re-chunk a source                    |
  | /model NAME      | Switch AI model                                     |
  | /clear           | Clear screen and reset message history              |
  | /compact         | Compact conversation to reduce token usage          |
  | /usage           | Show token usage and cost statistics                |
  | /tools           | Show available tools with tier assignments          |
  | /spec            | Manage specs (list/show/create/approve/unapprove/diff) |
  | /pack            | Manage packs (list/install/update/remove/attach/detach) |
  | /mcp             | Show MCP server status and tools                    |
  | /conventions     | Display space conventions (ANTEROOM.md)             |
  | /config          | Edit config interactively (TUI-based)               |
  | /plan            | Enter/exit planning mode                            |
  | /verbose         | Toggle verbosity level                              |
  | /quit            | Exit the REPL                                       |

  ### Space Instructions (ANTEROOM.md)

  Loaded automatically via walk-up discovery from cwd.
  Search filenames (first match wins): `.anteroom.md` > `ANTEROOM.md` > `.claude.md` > `CLAUDE.md`
  Trust: SHA-256 hash verified. Flags: `--trust-project`, `--no-project-context`.

  ### Directory Equivalence

  `.anteroom` and `.claude` directories are interchangeable:
  instructions, skills, team config, space config, rules.
  `.anteroom` takes precedence if both exist at the same level.

  ---

  ## Documentation Index

  Use `read_file` on these paths when the inline reference doesn't cover the question.

  **Getting Started**: `docs/getting-started/installation.md`, `docs/getting-started/quickstart.md`, `docs/getting-started/concepts.md`

  **CLI**: `docs/cli/commands.md` (full command ref), `docs/cli/tools.md` (tool signatures/args), `docs/cli/skills.md` (skill system), `docs/cli/skill-examples.md` (example skills with sub-agents), `docs/cli/porting-from-claude-code.md` (Claude Code migration), `docs/cli/context-management.md`, `docs/cli/file-references.md` (@file syntax), `docs/cli/project-instructions.md` (ANTEROOM.md)

  **Configuration**: `docs/configuration/config-file.md` (full config reference with all fields, types, defaults), `docs/configuration/environment-variables.md` (all AI_CHAT_* env vars), `docs/configuration/mcp-servers.md` (MCP setup), `docs/configuration/team-config.md` (team config, enforce, required)

  **Security**: `docs/security/tool-safety.md` (tiers, approval modes), `docs/security/bash-sandboxing.md` (bash sandbox), `docs/security/authentication.md` (auth, sessions, IP allowlist), `docs/security/audit-log.md` (audit logging), `docs/security/hardening.md` (hardening guide), `docs/security/prompt-injection-defense.md`, `docs/security/index.md`

  **Packs & Artifacts**: `docs/packs/index.md` (overview), `docs/packs/concepts.md` (types, FQN, precedence), `docs/packs/pack-commands.md` (CLI commands), `docs/packs/manifest-format.md` (pack.yaml), `docs/packs/artifact-types.md` (7 types), `docs/packs/health-check.md`, `docs/packs/troubleshooting.md`

  **Specs**: `docs/specs/index.md` (overview), `docs/specs/quickstart.md`, `docs/specs/concepts.md` (phases, invalidation, gates), `docs/specs/commands.md` (CLI ref), `docs/specs/schema-reference.md` (YAML format), `docs/specs/api-reference.md` (REST endpoints), `docs/specs/troubleshooting.md`

  **Spaces**: `docs/spaces/index.md` (overview), `docs/spaces/commands.md` (space commands), `docs/spaces/space-file-format.md`, `docs/spaces/config-overlay.md`

  **Knowledge & RAG**: `docs/knowledge/index.md`, `docs/knowledge/how-rag-works.md`, `docs/knowledge/sources.md`, `docs/knowledge/config-reference.md`

  **Web UI**: `docs/web-ui/conversations.md`, `docs/web-ui/spaces.md`, `docs/web-ui/attachments.md`, `docs/web-ui/streaming.md`, `docs/web-ui/keyboard-shortcuts.md`

  **Tutorials**: `docs/tutorials/connect-to-ollama.md` (local LLM), `docs/tutorials/connect-to-azure.md` (Azure), `docs/tutorials/add-mcp-tools.md` (MCP), `docs/tutorials/build-custom-skills.md`

  **API**: `docs/api/conversations.md`, `docs/api/messages.md`, `docs/api/spaces.md`, `docs/api/config.md`

  **Architecture**: `docs/advanced/architecture.md`, `docs/advanced/testing.md`, `docs/advanced/developer-workflow.md`

  ---

  ## Source Code Index

  Use `introspect section=package` to get the source root, then read files relative to it.

  | Area | Path |
  |------|------|
  | Entry points | `__main__.py`, `app.py` |
  | Config loading | `config.py` |
  | Agent loop | `services/agent_loop.py` |
  | AI providers | `services/ai_service.py`, `services/anthropic_provider.py` |
  | Storage/DB | `services/storage.py`, `db.py` |
  | Tool system | `tools/safety.py`, `tools/security.py`, `tools/tiers.py`, `tools/bash.py` |
  | Skills | `cli/skills.py`, `cli/default_skills/` |
  | Packs | `services/packs.py`, `services/pack_attachments.py`, `services/config_overlays.py` |
  | Spaces | `services/spaces.py`, `services/space_storage.py` |
  | Security | `services/audit.py`, `services/context_trust.py`, `services/dlp.py` |
  | CLI REPL | `cli/repl.py`, `cli/commands.py`, `cli/agent_turn.py` |
  | Web routers | `routers/chat.py`, `routers/sources.py`, `routers/spaces.py` |

  ---

  ## User's Question

  {args}
