docs: add SETUP-GUIDE.md + audit and fix all Perseus documentation

INSTALL.md

@@ -1,18 +1,24 @@
 # Installing Perseus
 
-Perseus is a single-file Python tool with a single dependency (`pyyaml`). The
-installer preserves that simplicity: no package managers, no virtualenv
-required, no source-checkout split.
+## Quick install (recommended)
 
-## Prerequisites
+```bash
+# via uv (fastest, isolated)
+uv tool install perseus-ctx
 
-- Python **3.10+**
-- `pyyaml`:
-  ```bash
-  python3 -m pip install --user pyyaml
-  ```
+# or via pip
+pip install perseus-ctx
 
-## Quick install (recommended)
+# verify
+perseus --version
+```
+
+> **Windows note:** `uv` may warn that `~/.local/bin` is not on your PATH. Add this to your shell rc:
+> ```bash
+> export PATH="$HOME/.local/bin:$PATH"
+> ```
+
+## Install from source
 
 From a checkout of this repo:
 
@@ -30,7 +36,11 @@ By default this installs:
 It then runs `perseus --version` to verify the install. Add `~/.local/bin` to
 your PATH if it isn't already.
 
-## Custom prefix
+## Prerequisites
+
+- Python **3.10+** (pyyaml is installed automatically as a dependency)
+
+## Custom prefix (source install)
 
 ```bash
 ./scripts/install.sh --prefix /opt/perseus

QUICKSTART.md

@@ -176,11 +176,25 @@ perseus render .perseus/context.md  # Verify it works
 ```
 
 Then create `.perseus/config.yaml`:
+
 ```yaml
+# ~/.perseus/config.yaml
+# ⚠ CRITICAL: render.allow_query_shell must be true for @query to work.
+# The trust section controls audit display only — NOT the render gate.
 render:
-  allow_query_shell: false
-permissions:
-  profile: balanced
+  allow_query_shell: true        # ← REQUIRED to enable @query
+  allow_agent_shell: true
+  allow_remote_services_health: true
+  allow_services_command: true
+  parallel_services: true
+  services_timeout_s: 3
+
+trust:
+  allow_query_shell: true        # controls audit display only
+  allow_outside_workspace: false
+  redact_secrets: true
+
+# Optional: LLM backend for Pythia suggestions & Synthesis
 generation:
   enabled: true
   model: gemini-2.5-flash
@@ -189,3 +203,5 @@ llm:
   model: gemini-2.5-flash
   url: https://generativelanguage.googleapis.com/v1beta
 ```
+
+> **See the full [Setup & Configuration Guide](./SETUP-GUIDE.md) for detailed config documentation, automation patterns, and troubleshooting.**

README.md

@@ -58,13 +58,14 @@ Pick your assistant and add the config block shown:
 ```yaml
 mcp_servers:
   perseus:
-    transport: stdio
     command: perseus
-    args: ["mcp", "serve"]
+    args: ["mcp", "serve", "--workspace", "/path/to/workspace"]
 ```
 
 Then verify with `hermes mcp test perseus`. Tools appear as `mcp_perseus_*` in your session.
 
+> Use an absolute path for `--workspace`. Perseus's non-interactive shell context has a limited PATH — a bare `perseus` command works in the Hermes MCP config because Hermes resolves it from the user's environment, but the workspace path must be absolute.
+
 **Claude Desktop** (`claude_desktop_config.json`):
 
 ```json
@@ -220,12 +221,14 @@ That's it. The output file name is the only assistant-specific detail:
 | Assistant | Output file |
 |---|---|
 | Claude Code | `CLAUDE.md` |
-| Hermes Agent | `.hermes.md` |
+| Hermes Agent | `.hermes.md` (top priority) or `AGENTS.md` |
 | Cursor | `.cursorrules` or `.cursor/context.md` |
 | Codex | `AGENTS.md` |
 | Rovo Dev | `AGENTS.md` |
 | Any other | Whatever your assistant reads at session start |
 
+> **Hermes priority order:** `.hermes.md` → `AGENTS.md` → `CLAUDE.md`. Render to `.hermes.md` for highest priority.
+
 Keep it fresh with cron, launchd, systemd, or `perseus watch`:
 
 ```bash
@@ -290,7 +293,7 @@ The `O_CREAT | O_EXCL` checkpoint locking is atomic on local POSIX filesystems.
 You write this:
 
 ```markdown
-@perseus v0.4
+@perseus v1.0.6
 
 # Context — @date format="YYYY-MM-DD HH:mm z"
 
@@ -416,7 +419,7 @@ Proven at enterprise scale — see [Multi-Agent Relay](./docs/EXAMPLES.md#subage
             ~/.perseus/formats/          ┘  and aliases load from config.
 
 Source document (.perseus/context.md)
-  @perseus v0.4
+  @perseus v1.0.6
   @query "git log --oneline -5"          ┐
   @read .env key="PORT"                  │  Directives resolved
   @waypoint ttl=86400                    │  before context window.
@@ -645,6 +648,7 @@ Mnēmē is LLM-optional: deterministic assembly works zero-dependency; an option
 | Document | What it covers |
 |---|---|
 | [**CLI Reference**](./docs/CLI.md) | Every command and flag |
+| [**Setup & Config Guide**](./SETUP-GUIDE.md) | The definitive setup, config, automation, and troubleshooting guide |
 | [**Directives Reference**](./docs/DIRECTIVES.md) | All directives with modifiers and examples |
 | [**Integration Guide**](./docs/HERMES_INTEGRATION.md) | Wire Perseus to Hermes via LLM routing |
 | [**Adapter Patterns**](./spec/integration.md) | Wire Perseus to any AI assistant |