harness_docs.rs

//! In-band harness documentation served via `catcode://` and `omp://`.
//!
//! These URIs resolve from the compiled binary — no workspace files required —
//! so an agent in any install can answer "how does the harness work?" and
//! "how do I add a tool / provider / plugin?". `omp://` is an alias of the
//! same tree (OMP-compatible).

use serde_json::Value;

/// One bundled skill (or extra file) staged into `~/.catalyst-code/` and
/// served from `catcode://skills/…` / `catcode://create/…`.
#[derive(Clone, Copy)]
pub struct BundledFile {
    /// Path relative to `~/.catalyst-code/` (e.g. `skills/add-core-tool/SKILL.md`).
    pub rel: &'static str,
    pub body: &'static str,
}

#[derive(Clone, Copy)]
struct SkillDoc {
    name: &'static str,
    description: &'static str,
    /// Path relative to `~/.catalyst-code/`.
    rel: &'static str,
    /// `SKILL.md` body.
    body: &'static str,
}

#[derive(Clone, Copy)]
struct CreateAlias {
    /// Filename under `create/` (`tool.md`).
    slug: &'static str,
    skill: &'static str,
    blurb: &'static str,
}

const CREATE_SKILL_GUIDE: &str = r#"# Write a skill

A skill is a directory with a `SKILL.md` the agent can apply via `/skill:<name>`
or read via `skill://<name>`. Project skills live in
`.catalyst-code/skills/<name>/`; user-global skills live in
`~/.catalyst-code/skills/<name>/` (project wins on name).

## Layout

    .catalyst-code/skills/<name>/
    ├── SKILL.md              # required
    └── references/…          # optional extras; read with skill://name/references/…

## SKILL.md frontmatter

```markdown
---
name: my-skill
description: One line the standing-prompt manifest shows (keep ≤80 chars)
version: 1
---

## When to use
…

## Steps
1. …
```

`name` should match the directory. `description` is what the orchestrator
sees in the capped skill manifest.

## Rules

- Keep the body a procedure, not a dump. Point at code paths (`file:line`)
  and existing patterns; do not invent a second convention.
- Skills on disk are opt-in. A capability that must work in a *fresh*
  install (no source tree) also needs an embedded pointer — see
  `catcode://create/prompt.md` / skill `add-embedded-prompt-knowledge`.
- First-party create-thing skills ship in the binary (`catcode://skills/`)
  and are staged into `~/.catalyst-code/skills/` on first run.

See also: `catcode://create/` for the shipped recipes.
"#;

const DOCS_OVERVIEW: &str = r#"# Catalyst Code — overview

Catalyst Code is a self-hosted coding-agent harness: one Rust core, a Go TUI,
a web hub, and a TypeScript SDK, speaking a stdio JSONL protocol.

## What you can ask this agent

- **How the harness works** — start at `catcode://docs/` (this tree).
- **How to extend it** — start at `catcode://create/` (add a tool, provider,
  plugin, config knob, panel, skill, …). Full manuals are also
  `skill://add-core-tool` and siblings.
- **What a built-in tool does** — `catcode://tools/<name>.md`.

`omp://` is an alias of `catcode://` (same documents).

## Components

| Piece | Role |
|-------|------|
| `core/` | Agent loop, tools, providers, plugins, memory, subagents |
| `tui/` | Terminal UI (`catcode`) |
| `web/` | Multi-session hub |
| `sdk/` | TypeScript adapter |

## Extend without a recompile (usual path)

1. **API-key provider** — config JSON; see `catcode://create/provider.md`.
2. **OAuth / login-flow provider** — plugin `oauth` block; `catcode://create/plugin.md`.
3. **Custom tool / hook / slash command** — plugin; `catcode://create/plugin.md`.
4. **Project procedure** — write a skill; `catcode://create/skill.md`.

## Extend the compiled core (this repo)

When you are *in the CatCode source tree* and the user wants a built-in:

- new tool → `catcode://create/tool.md`
- config knob → `catcode://create/config.md`
- blocking HITL tool → `catcode://create/blocking-tool.md`
- background task → `catcode://create/background-task.md`
- web IDE panel → `catcode://create/ide-panel.md`
- TUI tool renderer → `catcode://create/tui-renderer.md`
- standing-prompt knowledge → `catcode://create/prompt.md`

## Safety / loop

Destructive tools go through the approval gate. Workspace paths are confined.
Advisor/watchdog is on by default (fail-open). Sandbox defaults to Microsandbox
and degrades to host when preflight fails.
"#;

const DOCS_ARCHITECTURE: &str = r#"# Catalyst Code — architecture

One agent loop lives in the Rust core (`core/src`). The TUI and web hub are
thin clients over the JSONL protocol. Do not add a second loop.

## Core modules (where to look)

| Module | Role |
|--------|------|
| `core/src/main.rs` | Entry, standing prompt, dispatch |
| `core/src/agent/` | Turn loop, compaction |
| `core/src/tools.rs` | Unified read + sync tool execution |
| `core/src/tooling/` | Schemas, builtin tools, scheduler |
| `core/src/provider.rs` / `providers/` | Model streaming + first-party OAuth bundles |
| `core/src/plugins.rs` | Hooks, custom tools, OAuth, memory backends |
| `core/src/subagent.rs` | Child agents (single / parallel / chain) |
| `core/src/memory.rs` / `knowledge_tool.rs` | Durable memory + repo intelligence |
| `core/src/config.rs` | CLI + env + JSON layering |
| `core/src/staging.rs` | First-run `~/.catalyst-code/` defaults |
| `core/src/harness_docs.rs` | This `catcode://` / `omp://` tree |

## Protocol

TUI/web write `Command` lines to the core stdin and read `Event` lines from
stdout (`core/src/protocol.rs`, fixtures in `protocol/fixtures/`).

## Skills vs embedded knowledge

| Layer | Ships in a fresh install? |
|-------|---------------------------|
| Standing-prompt consts (`PLUGIN_DOCS`, `PROVIDER_GUIDE`, `HARNESS_DOCS_GUIDE`) | yes |
| `catcode://` documents (this module) | yes — in the binary |
| Staged skills under `~/.catalyst-code/skills/` | yes — first run |
| Project `.catalyst-code/skills/` | only if the repo added them |

Full create-thing manuals are both embedded here and staged globally so
`skill://add-core-tool` works in any workspace after first run.

See `catcode://docs/extend.md` and `catcode://create/`.
"#;

const DOCS_EXTEND: &str = r#"# Extending Catalyst Code

Pick the smallest path that matches the request. Read the recipe before
inventing a new convention.

| User said | Path | Recipe |
|-----------|------|--------|
| add / connect provider X (API key) | config, no recompile | `catcode://create/provider.md` |
| add provider X (OAuth / subscription) | plugin | `catcode://create/plugin.md` |
| write a plugin / hook / custom tool | plugin | `catcode://create/plugin.md` |
| add a built-in tool (this repo) | core | `catcode://create/tool.md` |
| add a config knob | core | `catcode://create/config.md` |
| add a blocking ask/approval tool | core | `catcode://create/blocking-tool.md` |
| add a periodic background task | core | `catcode://create/background-task.md` |
| add a web IDE panel | web/ | `catcode://create/ide-panel.md` |
| render a tool nicely in the TUI | tui/ | `catcode://create/tui-renderer.md` |
| make every session *know* how to do X | standing prompt | `catcode://create/prompt.md` |
| write a reusable procedure | skill | `catcode://create/skill.md` |
| parallelize this turn | ultrawork | `skill://ultrawork` |

Aliases: `omp://create/…` is the same tree.

Rule of thumb: **no-recompile first** (config / plugin / skill). Recompile
only when the user is in the CatCode source tree and the capability must be
built-in.
"#;

const SKILLS: &[SkillDoc] = &[
    SkillDoc {
        name: "add-core-tool",
        description: "Add a built-in tool (schema, classify, dispatch, guards)",
        rel: "skills/add-core-tool/SKILL.md",
        body: include_str!("../../.catalyst-code/skills/add-core-tool/SKILL.md"),
    },
    SkillDoc {
        name: "add-key-provider",
        description: "Add a key-auth model provider (config vs provider.rs)",
        rel: "skills/add-key-provider/SKILL.md",
        body: include_str!("../../.catalyst-code/skills/add-key-provider/SKILL.md"),
    },
    SkillDoc {
        name: "add-config-knob",
        description: "Add a configurable setting (struct, JSON, env, CLI, UI)",
        rel: "skills/add-config-knob/SKILL.md",
        body: include_str!("../../.catalyst-code/skills/add-config-knob/SKILL.md"),
    },
    SkillDoc {
        name: "add-embedded-prompt-knowledge",
        description: "Embed a lean standing-prompt pointer for a capability",
        rel: "skills/add-embedded-prompt-knowledge/SKILL.md",
        body: include_str!("../../.catalyst-code/skills/add-embedded-prompt-knowledge/SKILL.md"),
    },
    SkillDoc {
        name: "add-blocking-tool",
        description: "Add a HITL tool that blocks until the frontend answers",
        rel: "skills/add-blocking-tool/SKILL.md",
        body: include_str!("../../.catalyst-code/skills/add-blocking-tool/SKILL.md"),
    },
    SkillDoc {
        name: "add-core-background-task",
        description: "Add a periodic core background task (independent of turns)",
        rel: "skills/add-core-background-task/SKILL.md",
        body: include_str!("../../.catalyst-code/skills/add-core-background-task/SKILL.md"),
    },
    SkillDoc {
        name: "add-ide-panel",
        description: "Add a user-driven panel to the web IDE shell",
        rel: "skills/add-ide-panel/SKILL.md",
        body: include_str!("../../.catalyst-code/skills/add-ide-panel/SKILL.md"),
    },
    SkillDoc {
        name: "add-tui-tool-renderer",
        description: "Add a per-tool block renderer to the Go TUI",
        rel: "skills/add-tui-tool-renderer/SKILL.md",
        body: include_str!("../../.catalyst-code/skills/add-tui-tool-renderer/SKILL.md"),
    },
    SkillDoc {
        name: "plugin-authoring",
        description: "Author plugins: hooks, tools, OAuth, memory, prompt injection",
        rel: "skills/plugin-authoring/SKILL.md",
        body: include_str!("../../.catalyst-code/skills/plugin-authoring/SKILL.md"),
    },
    SkillDoc {
        name: "pi-subagents",
        description: "Orchestrator playbook for subagent / task / hub",
        rel: "skills/pi-subagents/SKILL.md",
        body: include_str!("../../.catalyst-code/skills/pi-subagents/SKILL.md"),
    },
    SkillDoc {
        name: "ultrawork",
        description: "In-session parallel execution (not /goal)",
        rel: "skills/ultrawork/SKILL.md",
        body: include_str!("../../.catalyst-code/skills/ultrawork/SKILL.md"),
    },
    SkillDoc {
        name: "explain-self-learning",
        description: "Explain the self-learning / memory system from architecture facts",
        rel: "skills/explain-self-learning/SKILL.md",
        body: include_str!("../../.catalyst-code/skills/explain-self-learning/SKILL.md"),
    },
];

const ULTRAWORK_TIERS: &str =
    include_str!("../../.catalyst-code/skills/ultrawork/references/agent-tiers.md");

const CREATE_ALIASES: &[CreateAlias] = &[
    CreateAlias {
        slug: "tool.md",
        skill: "add-core-tool",
        blurb: "Add a built-in core tool",
    },
    CreateAlias {
        slug: "provider.md",
        skill: "add-key-provider",
        blurb: "Add an API-key model provider",
    },
    CreateAlias {
        slug: "plugin.md",
        skill: "plugin-authoring",
        blurb: "Author a plugin (hooks, tools, OAuth)",
    },
    CreateAlias {
        slug: "config.md",
        skill: "add-config-knob",
        blurb: "Add a config / env / CLI knob",
    },
    CreateAlias {
        slug: "prompt.md",
        skill: "add-embedded-prompt-knowledge",
        blurb: "Teach every session a capability via the standing prompt",
    },
    CreateAlias {
        slug: "blocking-tool.md",
        skill: "add-blocking-tool",
        blurb: "Add a tool that blocks for a human answer",
    },
    CreateAlias {
        slug: "background-task.md",
        skill: "add-core-background-task",
        blurb: "Add a periodic core background task",
    },
    CreateAlias {
        slug: "ide-panel.md",
        skill: "add-ide-panel",
        blurb: "Add a web IDE panel",
    },
    CreateAlias {
        slug: "tui-renderer.md",
        skill: "add-tui-tool-renderer",
        blurb: "Add a TUI per-tool renderer",
    },
];

/// Files to materialize under `~/.catalyst-code/` on first run / schema bump.
pub fn bundled_skill_files() -> Vec<BundledFile> {
    let mut out: Vec<BundledFile> = SKILLS
        .iter()
        .map(|s| BundledFile {
            rel: s.rel,
            body: s.body,
        })
        .collect();
    out.push(BundledFile {
        rel: "skills/ultrawork/references/agent-tiers.md",
        body: ULTRAWORK_TIERS,
    });
    out
}

/// `SKILL.md` body for a shipped skill, if the binary embeds it.
pub fn embedded_skill_body(name: &str) -> Option<&'static str> {
    SKILLS
        .iter()
        .find(|s| s.name.eq_ignore_ascii_case(name))
        .map(|s| s.body)
}

/// Nested file under a shipped skill (`references/agent-tiers.md`).
pub fn embedded_skill_path(name: &str, rel: &str) -> Option<&'static str> {
    if rel.is_empty() || rel == "SKILL.md" {
        return embedded_skill_body(name);
    }
    if name.eq_ignore_ascii_case("ultrawork")
        && (rel == "references/agent-tiers.md" || rel == "references/agent-tiers")
    {
        return Some(ULTRAWORK_TIERS);
    }
    None
}

/// Resolve `catcode://…` or `omp://…`. Errors are user-facing `read:` messages.
pub fn read_uri(uri: &str) -> Result<String, String> {
    let (scheme, path) = split_scheme(uri)?;
    if !safe_path(path) {
        return Err(format!("read: unsafe {scheme} URI"));
    }
    let path = path.trim_matches('/');
    match path {
        "" => Ok(render_index(scheme)),
        "tools" => Ok(render_tools_index(scheme)),
        "create" => Ok(render_create_index(scheme)),
        "docs" => Ok(render_docs_index(scheme)),
        "skills" => Ok(render_skills_index(scheme)),
        "docs/overview.md" | "docs/overview" => Ok(DOCS_OVERVIEW.to_string()),
        "docs/architecture.md" | "docs/architecture" => Ok(DOCS_ARCHITECTURE.to_string()),
        "docs/extend.md" | "docs/extend" => Ok(DOCS_EXTEND.to_string()),
        "create/skill.md" | "create/skill" => Ok(CREATE_SKILL_GUIDE.to_string()),
        other => {
            if let Some(rest) = other.strip_prefix("tools/") {
                return read_tool_doc(scheme, rest);
            }
            if let Some(rest) = other.strip_prefix("create/") {
                return read_create(scheme, rest);
            }
            if let Some(rest) = other.strip_prefix("skills/") {
                return read_skill_doc(scheme, rest);
            }
            Err(unknown_doc(scheme, other))
        }
    }
}

fn split_scheme(uri: &str) -> Result<(&str, &str), String> {
    if let Some(rest) = uri.strip_prefix("catcode://") {
        return Ok(("catcode", rest));
    }
    if let Some(rest) = uri.strip_prefix("omp://") {
        return Ok(("omp", rest));
    }
    Err("read: invalid harness-docs URI (use catcode:// or omp://)".into())
}

fn safe_path(path: &str) -> bool {
    if path.contains('\0') || path.contains('\\') || path.contains("..") {
        return false;
    }
    if path.starts_with('/') && path != "/" {
        return false;
    }
    true
}

fn render_index(scheme: &str) -> String {
    let mut out = format!(
        "# Catalyst Code harness documentation\n\n\
         In-band docs (no workspace files required). Read any path with `read_file`.\n\
         `omp://` and `catcode://` are the same tree.\n\n\
         ## Start here\n\n\
         - `{scheme}://` — this index\n\
         - `{scheme}://docs/` — what the harness is, architecture, how to extend\n\
         - `{scheme}://create/` — add a tool, provider, plugin, config, skill, …\n\
         - `{scheme}://tools/` — built-in tool contracts\n\
         - `{scheme}://skills/` — shipped create-thing and orchestrator skills\n\n\
         Ask about the harness → `{scheme}://docs/`.\n\
         Want to add something → `{scheme}://create/`.\n\n\
         ## Documents\n\n\
         - `{scheme}://docs/overview.md`\n\
         - `{scheme}://docs/architecture.md`\n\
         - `{scheme}://docs/extend.md`\n\
         - `{scheme}://create/skill.md`\n"
    );
    for alias in CREATE_ALIASES {
        out.push_str(&format!(
            "- `{scheme}://create/{slug}`\n",
            slug = alias.slug
        ));
    }
    out.push('\n');
    out.push_str(&render_tools_index(scheme));
    out
}

fn render_docs_index(scheme: &str) -> String {
    format!(
        "# Harness docs\n\n\
         - `{scheme}://docs/overview.md` — what Catalyst Code is\n\
         - `{scheme}://docs/architecture.md` — components and where to look\n\
         - `{scheme}://docs/extend.md` — decision table for adding things\n\
         - `{scheme}://create/` — full create-thing recipes\n\
         - `{scheme}://tools/` — built-in tool contracts\n\
         - `{scheme}://skills/` — shipped skill manuals\n"
    )
}

fn render_create_index(scheme: &str) -> String {
    let mut out = format!(
        "# Create-thing recipes\n\n\
         Read a recipe, then follow it. Do not invent a second convention.\n\n\
         - `{scheme}://create/skill.md` — write a skill (any workspace)\n"
    );
    for alias in CREATE_ALIASES {
        out.push_str(&format!(
            "- `{scheme}://create/{slug}` — {blurb} (`skill://{skill}`)\n",
            slug = alias.slug,
            blurb = alias.blurb,
            skill = alias.skill
        ));
    }
    out.push_str("\nAlso: `skill://ultrawork` (parallel execution), `skill://pi-subagents` (orchestrator playbook).\n");
    out
}

fn render_skills_index(scheme: &str) -> String {
    let mut out = String::from("# Shipped skills\n\nThese manuals live in the binary and are staged to `~/.catalyst-code/skills/`.\n\n");
    for skill in SKILLS {
        out.push_str(&format!(
            "- `{scheme}://skills/{name}` — {desc}\n",
            name = skill.name,
            desc = skill.description
        ));
    }
    out.push_str(
        "\nNested: `catcode://skills/ultrawork/references/agent-tiers.md`.\n\
         Disk: `skill://<name>` after first-run staging (project `.catalyst-code/skills/` still wins).\n",
    );
    out
}

fn tool_entries() -> Vec<(String, Value)> {
    crate::tooling::schema::definitions()
        .into_iter()
        .filter_map(|definition| {
            let function = definition.get("function")?.clone();
            let name = function.get("name")?.as_str()?.trim().to_string();
            (!name.is_empty()).then_some((name, function))
        })
        .collect()
}

fn render_tools_index(scheme: &str) -> String {
    let mut out = format!("# Built-in tools\n\n- `{scheme}://`\n");
    for (name, _) in tool_entries() {
        out.push_str(&format!("- `{scheme}://tools/{name}.md`\n"));
    }
    out
}

fn read_tool_doc(scheme: &str, rest: &str) -> Result<String, String> {
    let requested = rest
        .strip_suffix(".md")
        .unwrap_or(rest)
        .trim()
        .trim_matches('/');
    if requested.is_empty() || requested.contains('/') {
        return Err(unknown_doc(scheme, rest));
    }
    let tools = tool_entries();
    if let Some((name, function)) = tools
        .iter()
        .find(|(name, _)| name.eq_ignore_ascii_case(requested))
    {
        return Ok(format_tool_doc(name, function));
    }
    let needle = requested.to_ascii_lowercase();
    let suggestions: Vec<&str> = tools
        .iter()
        .map(|(name, _)| name.as_str())
        .filter(|name| {
            let lower = name.to_ascii_lowercase();
            lower.starts_with(&needle) || lower.contains(&needle)
        })
        .take(5)
        .collect();
    let mut message = format!(
        "read: unknown {scheme} tool '{requested}'. Use {scheme}:// to list available files."
    );
    if !suggestions.is_empty() {
        message.push_str(" Close matches: ");
        message.push_str(&suggestions.join(", "));
    }
    Err(message)
}

fn format_tool_doc(name: &str, function: &Value) -> String {
    let description = function
        .get("description")
        .and_then(Value::as_str)
        .unwrap_or("");
    let mut output = format!("# {name}\n\n{description}\n\n## Parameters\n");
    let required: Vec<&str> = function
        .get("parameters")
        .and_then(|p| p.get("required"))
        .and_then(Value::as_array)
        .map(|arr| arr.iter().filter_map(Value::as_str).collect())
        .unwrap_or_default();
    if let Some(properties) = function
        .get("parameters")
        .and_then(|p| p.get("properties"))
        .and_then(Value::as_object)
    {
        for (key, spec) in properties {
            let ty = spec.get("type").and_then(Value::as_str).unwrap_or("any");
            let desc = spec
                .get("description")
                .and_then(Value::as_str)
                .unwrap_or("");
            let req = if required.iter().any(|r| *r == key) {
                "required"
            } else {
                "optional"
            };
            if desc.is_empty() {
                output.push_str(&format!("- `{key}` ({ty}, {req})\n"));
            } else {
                output.push_str(&format!("- `{key}` ({ty}, {req}) — {desc}\n"));
            }
        }
    }
    output
}

fn read_create(scheme: &str, rest: &str) -> Result<String, String> {
    let slug = if rest.ends_with(".md") {
        rest.to_string()
    } else {
        format!("{rest}.md")
    };
    if slug == "skill.md" {
        return Ok(CREATE_SKILL_GUIDE.to_string());
    }
    if let Some(alias) = CREATE_ALIASES.iter().find(|a| a.slug == slug) {
        if let Some(body) = embedded_skill_body(alias.skill) {
            return Ok(body.to_string());
        }
    }
    Err(unknown_doc(scheme, &format!("create/{rest}")))
}

fn read_skill_doc(scheme: &str, rest: &str) -> Result<String, String> {
    let rest = rest.trim_matches('/');
    let (name, rel) = match rest.split_once('/') {
        Some((name, rel)) => (name, rel),
        None => (rest.strip_suffix(".md").unwrap_or(rest), ""),
    };
    if let Some(body) = embedded_skill_path(name, rel) {
        return Ok(body.to_string());
    }
    if rel.is_empty() {
        if let Some(body) = embedded_skill_body(name) {
            return Ok(body.to_string());
        }
    }
    Err(unknown_doc(scheme, &format!("skills/{rest}")))
}

fn unknown_doc(scheme: &str, requested: &str) -> String {
    format!(
        "read: unknown {scheme} document '{requested}'. Use {scheme}:// to list available files."
    )
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn index_lists_create_docs_and_tools_for_both_schemes() {
        for scheme in ["catcode://", "omp://"] {
            let index = read_uri(scheme).expect(scheme);
            assert!(index.contains(&format!("{scheme}tools/read.md")), "{index}");
            assert!(index.contains(&format!("{scheme}tools/eval.md")), "{index}");
            assert!(index.contains(&format!("{scheme}create/")), "{index}");
            assert!(index.contains(&format!("{scheme}docs/")), "{index}");
            assert!(index.contains(&format!("{scheme}skills/")), "{index}");
        }
    }

    #[test]
    fn create_recipes_serve_skill_bodies() {
        let tool = read_uri("catcode://create/tool.md").unwrap();
        assert!(tool.contains("add-core-tool"), "{tool}");
        assert!(tool.contains("definitions()"), "{tool}");
        let plugin = read_uri("omp://create/plugin.md").unwrap();
        assert!(plugin.contains("plugin.json"), "{plugin}");
        let skill = read_uri("catcode://create/skill.md").unwrap();
        assert!(skill.contains("SKILL.md"), "{skill}");
    }

    #[test]
    fn docs_and_skills_resolve() {
        let overview = read_uri("catcode://docs/overview.md").unwrap();
        assert!(overview.contains("Catalyst Code"), "{overview}");
        let extend = read_uri("omp://docs/extend.md").unwrap();
        assert!(extend.contains("create/tool.md"), "{extend}");
        let listed = read_uri("catcode://skills/").unwrap();
        assert!(listed.contains("add-core-tool"), "{listed}");
        let body = read_uri("catcode://skills/add-core-tool").unwrap();
        assert!(body.contains("When to use"), "{body}");
        let tiers = read_uri("catcode://skills/ultrawork/references/agent-tiers.md").unwrap();
        assert!(!tiers.is_empty());
    }

    #[test]
    fn tool_docs_include_parameter_names() {
        let doc = read_uri("omp://tools/read.md").unwrap();
        assert!(doc.contains("## Parameters"), "{doc}");
        assert!(doc.contains("`path`"), "{doc}");
        let alias = read_uri("catcode://tools/read_file.md").unwrap();
        assert!(alias.contains("`path`"), "{alias}");
    }

    #[test]
    fn rejects_escapes_and_unknowns() {
        for uri in [
            "omp://../secret",
            "catcode://../secret",
            "catcode:///etc/passwd",
        ] {
            let err = read_uri(uri).unwrap_err();
            assert!(err.contains("unsafe"), "{uri}: {err}");
        }
        let unknown = read_uri("omp://tools/not-a-tool.md").unwrap_err();
        assert!(unknown.contains("omp://"), "{unknown}");
        let missing = read_uri("catcode://nope.md").unwrap_err();
        assert!(missing.contains("catcode://"), "{missing}");
    }

    #[test]
    fn embedded_lookup_matches_names() {
        assert!(embedded_skill_body("add-core-tool")
            .unwrap()
            .contains("add-core-tool"));
        assert!(embedded_skill_body("ADD-CORE-TOOL").is_some());
        assert!(embedded_skill_path("ultrawork", "references/agent-tiers.md").is_some());
        assert!(embedded_skill_body("not-a-skill").is_none());
    }

    #[test]
    fn bundled_files_cover_create_skills_and_ultrawork_ref() {
        let files = bundled_skill_files();
        let rels: Vec<_> = files.iter().map(|f| f.rel).collect();
        assert!(rels.contains(&"skills/add-core-tool/SKILL.md"));
        assert!(rels.contains(&"skills/plugin-authoring/SKILL.md"));
        assert!(rels.contains(&"skills/pi-subagents/SKILL.md"));
        assert!(rels.contains(&"skills/ultrawork/references/agent-tiers.md"));
        assert!(files.iter().all(|f| !f.body.is_empty()));
    }
}