feat: Add Amp Docs Search skill

.agents/skills/searching-amp-docs/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: searching-amp-docs
+description: Searches current official Amp documentation and gives source-backed explanations of Amp features, setup, CLI usage, modes, threads, projects, orbs, runners, tools, skills, MCP, plugins, SDKs, configuration, security, pricing, and troubleshooting. Use whenever a user asks how Amp works, what Amp supports, how Amp features compare, whether behavior is current or documented, or how to accomplish something with Amp—even if they do not explicitly ask to search the docs.
+---
+
+# Searching Amp Docs
+
+Answer questions about Amp from current, official documentation. Optimize explanations for users who may not know Amp terminology yet.
+
+## Documentation Sources
+
+Use these sources for different purposes:
+
+- [Amp's official `llms.txt`](https://ampcode.com/llms.txt) is the machine-readable documentation entrypoint. It currently links only to the manual and SDK.
+- [The Amp manual](https://ampcode.com/manual) is the primary source for product behavior and workflows.
+- Specialized official pages listed in [references/docs-index.md](references/docs-index.md) are authoritative for their exact contracts, such as SDK and Plugin API details.
+- Other official `ampcode.com` pages may cover current models, pricing, security, service status, account settings, or release announcements.
+
+The bundled index expands `llms.txt` for topic discovery, but it is not an authoritative or frozen copy of the documentation. Amp changes quickly. Read the relevant live page before answering factual questions; do not answer from either index or model memory alone.
+
+## Workflow
+
+1. Identify the user's actual goal and likely topic. Translate informal terms when necessary—for example, “cloud machine” likely means an orb and “rules file” likely means `AGENTS.md`.
+2. Read `references/docs-index.md` only as much as needed to choose the best official page and section.
+3. Fetch the selected page with `read_web_page`:
+   - Give it a specific objective containing the user's question and relevant terminology.
+   - Use `fullContent: true` when auditing a contract, comparing options, extracting every field, or checking whether a feature is documented.
+   - Use `forceRefetch: true` for “latest/current” questions and volatile information such as models, modes, pricing, limits, settings, or supported platforms.
+4. If the index is missing the topic or a link is stale, check the live [`llms.txt`](https://ampcode.com/llms.txt), then use `web_search` with `site:ampcode.com` queries and read the most relevant official result. Do not substitute blogs or third-party tutorials when official documentation exists.
+5. Read enough surrounding context to determine scope, prerequisites, defaults, and whether guidance is current. Search results and isolated excerpts can omit qualifiers.
+6. If official pages conflict, prefer the more specific current reference over summaries, report the conflict, and avoid silently combining incompatible guidance. Use release history or source code only when the official docs are incomplete, and label that evidence separately.
+7. Answer the goal directly. Include:
+   - a plain-language explanation;
+   - exact commands, settings, file locations, or code when useful;
+   - prerequisites, scope, defaults, and important caveats;
+   - links to the specific official pages used.
+8. If the official docs do not answer the question, say so clearly. Separate documented behavior from any reasonable inference and suggest the narrowest next step, such as `amp --help`, `amp tools list`, `amp config keymap`, the service-status page, or Amp support.
+
+## New-User Guidance
+
+- Define Amp-specific terms on first use: thread, mode, project, orb, runner, skill, plugin, MCP server, Oracle, Librarian, and Painter.
+- Prefer a short recommended path before listing alternatives.
+- Explain where to run commands and whether a file is user-wide, workspace-specific, or committed to a repository.
+- When several features overlap, compare them explicitly. Common distinctions include:
+  - local CLI vs orb vs runner;
+  - `AGENTS.md` vs skill vs plugin vs MCP;
+  - main agent vs subagent vs Oracle vs Librarian;
+  - thread visibility vs project membership;
+  - CLI execute mode vs SDK;
+  - `.agents/setup` vs `.agents/resume` vs `.amp/services.yaml`.
+- Preserve the user's operating system and interface context. Do not give macOS-only clipboard or path instructions to a Windows/WSL user.
+- Never invent a command, flag, setting, API field, keybinding, model assignment, price, or limit. Verify exact syntax in the live docs.
+
+## Answer Patterns
+
+### “How do I …?”
+
+Give the shortest working sequence first, then explain what each step does and mention only relevant alternatives.
+
+### “What is …?”
+
+Give a one-sentence definition, when to use it, one concrete example, and the official reference.
+
+### Comparison or Architecture Question
+
+Use a compact table when it improves clarity. Compare purpose, where it runs, persistence/scope, cost or security implications when documented, and the recommended use case.
+
+### Troubleshooting
+
+1. Confirm the platform, interface, and exact failure.
+2. Check documented prerequisites and diagnostics.
+3. Provide safe diagnostic commands before suggesting configuration changes.
+4. For outages, check [Amp service status](https://ampcodestatus.com).
+5. For unresolved client issues, explain how to generate a diagnostic report and contact support without exposing secrets.
+
+### “Show me every Amp feature”
+
+Do not paste the whole manual. Use the feature map in `references/docs-index.md` to provide a structured learning path, then offer to walk through one area with live documentation. A useful progression is:
+
+1. installation, interfaces, modes, and prompting;
+2. threads, file mentions, images, and `AGENTS.md`;
+3. projects, orbs, runners, and remote control;
+4. built-in tools, skills, subagents, Oracle, Librarian, and Painter;
+5. review checks, MCP, plugins, and permissions;
+6. CLI automation, configuration, and SDKs;
+7. pricing, enterprise controls, security, and troubleshooting.
+
+## Citation Rules
+
+- Link claims to the most specific official page available.
+- For the large main manual, use the section anchor from the index when possible.
+- Cite specialized references for exact SDK or plugin API contracts.
+- Do not imply that this skill's bundled index is maintained by Amp or replaces the official manual.

.agents/skills/searching-amp-docs/references/docs-index.md

@@ -0,0 +1,142 @@
+# Amp Official Documentation Index
+
+This is an expanded routing index for Amp's documentation. It complements the sparse public `llms.txt`; the linked live pages remain authoritative.
+
+## Start Here
+
+- [Owner's Manual](https://ampcode.com/manual) — primary guide to installing, using, extending, configuring, and paying for Amp
+- [Installation](https://ampcode.com/install) — account-specific installation and editor integration instructions
+- [Modes and models](https://ampcode.com/modes) — current mode-to-model assignments
+- [Pricing](https://ampcode.com/pricing) — current plan and usage pricing
+- [Service status](https://ampcodestatus.com) — incidents and uptime
+- [Support](https://ampcode.com/support) — official help channels
+
+## Owner's Manual Feature Map
+
+### Fundamentals
+
+- [Why Amp](https://ampcode.com/manual#why-amp) — product philosophy: multi-model, opinionated, frontier, and thread-based
+- [Get started](https://ampcode.com/manual#get-started) — sign-in, CLI installation, updates, and initial setup
+- [IDE integrations](https://ampcode.com/manual#ide) — VS Code-family editors, JetBrains, Neovim, Zed, and `ide connect`
+- [Agent modes](https://ampcode.com/manual#agent-modes) — low, medium, high, and ultra
+- [How to prompt](https://ampcode.com/manual#how-to-prompt) — task scoping, explicit context, planning-only requests, and verification guidance
+
+### Context and Interaction
+
+- [`AGENTS.md`](https://ampcode.com/manual#AGENTS.md) — project, subtree, personal, and organization guidance; fallback filenames
+- [Granular guidance](https://ampcode.com/manual#AGENTS.md) — file mentions, globbed references, and scoped frontmatter rules
+- [Referencing threads](https://ampcode.com/manual#referencing-threads) — reuse another thread by URL, ID, or `@@` search
+- [Finding threads](https://ampcode.com/manual#finding-threads) — keyword and filter-based thread search
+- [Archiving threads](https://ampcode.com/manual#archiving) — remove threads from the active list while retaining access
+- [Attaching images](https://ampcode.com/manual#images) — clipboard and file-path image inputs
+- [Mentioning files](https://ampcode.com/manual#mentioning-files) — add workspace files with `@`
+- [Message editing and queueing](https://ampcode.com/manual#usage) — edit, queue, steer, or interrupt messages
+
+### Projects and Remote Execution
+
+- [Projects](https://ampcode.com/manual#projects) — repository, settings, secrets, and related threads
+- [Repository](https://ampcode.com/manual#repository) — GitHub, Git URL, or Amp-hosted repositories
+- [Changes workflow](https://ampcode.com/manual#changes-workflow) — ship directly or push a branch/PR
+- [Orbs overview](https://ampcode.com/manual#orbs) — remote machines for unsupervised agent work
+- [Full Orbs manual](https://ampcode.com/manual/orbs) — sizes, billing, terminal, sync, setup, secrets, services, and portals
+- [Runners](https://ampcode.com/manual#runners) — let ampcode.com start threads on a live machine running Amp
+- [Thread sharing](https://ampcode.com/manual#thread-sharing) — unlisted, workspace, group, and private visibility
+- [Remote control](https://ampcode.com/manual#remote-control) — continue a running CLI thread from the web
+
+### Tools and Agent Capabilities
+
+- [Tools](https://ampcode.com/manual#tools) — built-in tools, trust model, and `amp tools list`
+- [Agent skills](https://ampcode.com/manual#agent-skills) — task-specific instructions/resources and installation locations
+- [Subagents](https://ampcode.com/manual#subagents) — isolated delegated work for complex or parallel tasks
+- [Oracle](https://ampcode.com/manual#oracle) — frontier-model second opinion for hard reasoning, debugging, and review
+- [Librarian](https://ampcode.com/manual#librarian) — deep search and explanation of public or connected private GitHub repositories
+- [Painter](https://ampcode.com/manual#painter) — image generation and editing
+- [Code review](https://ampcode.com/manual#code-review) — `amp review`, review requests, and custom checks
+
+### Extending Amp
+
+- [MCP](https://ampcode.com/manual#mcp) — local and remote Model Context Protocol servers
+- [MCP OAuth](https://ampcode.com/manual#mcp-oauth) — automatic and manual OAuth for remote servers
+- [Workspace MCP trust](https://ampcode.com/manual#mcp) — approval of workspace-defined servers
+- [MCP best practices](https://ampcode.com/manual#mcp) — skill bundling, focused tool sets, and loading precedence
+- [Permissions](https://ampcode.com/manual#permissions) — default tool behavior and plugin-based policy controls
+- [Plugins](https://ampcode.com/manual#plugins) — TypeScript extensions for events, tools, commands, UI, and AI classification
+- [Plugin locations](https://ampcode.com/manual#plugin-locations) — project, system, and workspace-global scopes
+- [Writing plugins](https://ampcode.com/manual#writing-plugins) — lifecycle, reload, and plugin structure
+- [Plugin events](https://ampcode.com/manual#event-examples) — `session.start`, `agent.start/end`, `tool.call/result`
+- [Plugin commands, tools, UI, and agents](https://ampcode.com/manual#command-tool-and-ui-examples) — registration and custom agent examples
+- [Plugin API reference](https://ampcode.com/manual/plugin-api) — end-to-end example and generated `@ampcode/plugin` types
+
+### CLI and Automation
+
+- [CLI](https://ampcode.com/manual#cli) — interactive mode, piped input, execute mode, and flags
+- [Keybindings](https://ampcode.com/manual#cli-keymap) — command palette, shortcuts, and `amp.keymap`
+- [Non-interactive environments](https://ampcode.com/manual#cli-non-interactive-environments) — API-key authentication for scripts and CI
+- [CLI–IDE integration](https://ampcode.com/manual#cli-editor-integration) — editor context and undo-aware edits
+- [Writing prompts in the CLI](https://ampcode.com/manual#cli-writing-prompts) — newlines, `$EDITOR`, and terminal behavior
+- [Streaming JSON](https://ampcode.com/manual#cli-streaming-json) — structured output and streaming input flags
+- [Stream JSON schema and examples](https://ampcode.com/manual/appendix#stream-json-output) — message types, subagents, images, and Claude Code compatibility
+
+### Configuration, Accounts, and Operations
+
+- [Configuration](https://ampcode.com/manual#configuration) — user/workspace settings locations and precedence
+- [Settings reference](https://ampcode.com/manual#core-settings) — supported `amp.*` settings, types, and defaults
+- [Enterprise managed settings](https://ampcode.com/manual#enterprise-managed-policy-settings) — organization-enforced machine policies
+- [Proxies and certificates](https://ampcode.com/manual#configuration) — `HTTP_PROXY`, `HTTPS_PROXY`, and custom CA certificates
+- [Pricing](https://ampcode.com/manual#pricing) — usage billing, credits, and subscription guidance
+- [Enterprise](https://ampcode.com/manual#enterprise) — SSO, ZDR, controls, APIs, groups, retention, and regional providers
+- [Support and platforms](https://ampcode.com/manual#support) — help channels and supported operating systems/editors
+
+## Orbs Manual Map
+
+- [What are orbs](https://ampcode.com/manual/orbs) — fresh per-thread remote machines and project configuration
+- [Orb pricing and sizes](https://ampcode.com/manual/orbs) — CPU, memory, disk, billing, pause behavior
+- [Starting orb threads](https://ampcode.com/manual/orbs) — web, `amp -ox`, TUI, and plugin APIs
+- [Review, terminal, and `amp sync`](https://ampcode.com/manual/orbs) — inspect remote work and mirror it locally
+- [Secrets and environment variables](https://ampcode.com/manual/orbs) — project runtime configuration
+- [OIDC workload identity](https://ampcode.com/manual/orbs) — short-lived identity tokens for external services
+- [Orb environment](https://ampcode.com/manual/orbs) — OS and preinstalled development tools
+- [Setup files](https://ampcode.com/manual/orbs) — `.agents/setup`, `.agents/resume`, `.amp/services.yaml`, and portal manifests
+- [Portals](https://ampcode.com/manual/orbs) — authenticated access to development servers in an orb
+
+## SDK Documentation
+
+- [SDK overview and guide](https://ampcode.com/manual/sdk) — streaming, conversations, thread continuity, configuration, MCP, and skills
+- [TypeScript reference](https://ampcode.com/manual/sdk/typescript) — complete TypeScript functions, types, inputs, and messages
+- [Python reference](https://ampcode.com/manual/sdk/python) — complete Python functions, types, inputs, and messages
+- [Access tokens](https://ampcode.com/settings/security#access-token) — SDK and non-interactive authentication
+
+SDK guide topics include installation, `execute()`, message streaming, result extraction, working directory, logging, modes, reasoning effort, labels, visibility, permissions, cancellation, MCP, multi-turn input, settings files, and custom skills.
+
+## Appendix and Specialized References
+
+- [Appendix](https://ampcode.com/manual/appendix) — diagnostics, tmux, service status, enterprise controls, and Stream JSON
+- [Generate a diagnostic report](https://ampcode.com/manual/appendix#report) — CLI/web reports and support workflow
+- [Amp CLI in tmux](https://ampcode.com/manual/appendix#amp-cli-tmux) — extended keys and multiline input
+- [MCP registry allowlist](https://ampcode.com/manual/appendix#mcp-registry-allowlist) — enterprise registry enforcement
+- [Workspace thread visibility controls](https://ampcode.com/manual/appendix#workspace-thread-visibility-controls) — sharing restrictions and private defaults
+- [Workspace entitlements](https://ampcode.com/manual/appendix#workspace-entitlements) — enterprise quotas and assignment precedence
+- [Legacy permissions rules](https://ampcode.com/manual/appendix/legacy-permissions-rules.txt) — old settings compatibility; prefer current plugin policies for new work
+- [Security reference](https://ampcode.com/security) — architecture, providers, retention, prompt injection defenses, audit logging, and disclosures
+- [Workspace OpenAPI schema](https://ampcode.com/api/v2/openapi.json) — enterprise analytics and data-management API contract
+
+## Topic Synonyms for Search
+
+Use these mappings when a user's language differs from the manual:
+
+| User wording | Search/documentation topic |
+| --- | --- |
+| cloud VM, sandbox, remote machine | orb |
+| local remote worker, self-hosted worker | runner |
+| conversation, session, chat | thread |
+| rules, instructions, memory | `AGENTS.md`, granular guidance |
+| reusable prompt, workflow package | agent skill |
+| extension, hook, custom command | plugin |
+| external tools, tool server | MCP |
+| second opinion, deep review | Oracle |
+| search GitHub or dependency source | Librarian |
+| generate/edit an image | Painter |
+| headless, CI, scripting | execute mode, Stream JSON, or SDK |
+| preview localhost remotely | orb portal |
+| startup script, install dependencies | `.agents/setup` |
+| restart server after orb wakes | `.agents/resume`, services |