README as docs; fold OMP into Pi footnote

[yourconscience]

Two changes:

1. README rework. With no docs site, the README now carries that role: Why → Quick start (full setup walkthrough) → What it syncs → per-surface guides (skills, external pinning, MCP, roles, hooks/memory) → command reference → configuration (resolution order, local overlay) → troubleshooting (incl. legacy pi→omp note) → comparison. Generated skills block untouched.

2. OMP folded into Pi. OMP no longer appears as a separate harness in comparisons — the README table, harness-map (HTML + regenerated PNG), and landing page now show Pi* with a footnote: vanilla pi is skills-only by design; on the OMP fork dotagents additionally manages roles and MCP. No code changes — the omp adapter still works.

Summary by Sourcery

Rework the README into a comprehensive, user-facing documentation hub and update harness documentation to fold the OMP fork into Pi with clarified support details.

Enhancements:

• Simplify and update descriptions of supported harnesses and sync surfaces in README, the landing page, and harness map, including Amp/OpenCode/OpenClaw compatibility-only notes.
• Consolidate Pi and OMP into a single Pi entry across docs, harness maps, and support matrices while preserving details on additional capabilities provided by the OMP fork.

Documentation:

• Restructure README into a full docs-style guide covering motivation, quick start, sync surfaces, skills, MCP, roles, hooks/memory, commands, configuration, troubleshooting, and comparisons.
• Clarify skill, MCP, role, and hook concepts, external skills pinning/audit behavior, memory tiers, and configuration resolution/local overlays in README.
• Document Pi/OMP behavior via a footnote and troubleshooting note, emphasizing Pi as skills-only and OMP as an extended fork managed under the same Pi entry.

[sourcery-ai]

Reviewer's Guide

README is reworked into the primary documentation, expanding and restructuring content around workflow, commands, configuration, and troubleshooting, while Pi/OMP support is now described as a single Pi* harness with a footnote clarifying that OMP extends Pi with roles and MCP; related comparison tables and docs pages are updated accordingly.

File-Level Changes

Change	Details	Files
README is promoted to be the primary docs source with a full information architecture covering motivation, setup, surfaces, workflows, commands, configuration, troubleshooting, and comparisons.	Rewrites the introduction to clearly separate the private ~/.agents repo from the public CLI and describe cross-harness syncing behavior. Adds a 'Why' section explaining the dotfiles-style design, user-level vs project-level scope, and separation of tool vs user config. Expands 'Quick start' into a guided, multi-step setup flow including starter content, harness detection, import behavior, git setup, and verification commands. Clarifies 'What it syncs' to enumerate the four surfaces and how each is rendered into native harness formats, including an updated support table. Introduces detailed sections for skills, external skills, MCP servers, agent roles, hooks/memory tiers, command reference, configuration resolution/overlays, starter content, troubleshooting, comparison to other tools, and license.	README.md
Documentation about Pi and OMP is consolidated so that Pi* represents both, with a footnote explaining that vanilla Pi is skills-only and the OMP fork additionally supports roles and MCP; OMP is removed as a separate harness from docs and maps.	Updates the README harness support table to show Pi* with footnote-based explanation of vanilla Pi vs OMP fork capabilities and sync surfaces. Adjusts troubleshooting notes to explain behavior when upgrading from configs that targeted Pi with MCP and how to rename to OMP in dotagents.yaml if desired. Removes the separate OMP card from the docs site supported-harness list, folding OMP behavior into Pi’s card via HTML comments and descriptive copy. Modifies the docs site sync-surface comparison table to use a single Pi* row and adds explanatory footnote text about OMP’s additional roles/MCP management. Updates the harness-map HTML to remove the standalone OMP card, expand the Pi card chips to indicate skills-only design and OMP fork capabilities, and revises the managed support matrix to use Pi* with a clarifying footnote. Adjusts meta description and footer text in docs pages to no longer list OMP as a separate primary harness while still reflecting Pi support and OMP behavior via notes.	README.md docs/site/index.html docs/harness-map.html

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e98da9e167

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Document the PR behavior of skill promote

In this local-canonicalization example, the command is described as just finding a native skill and copying it under ~/.agents, but runPromote only skips the git checkout/commit/push and gh pr create path when --dry-run is supplied. In a configured repo this can create a branch/PR, or fail after changing branches, for users who only wanted to copy a harness-local skill; please include --dry-run here or explicitly describe the PR behavior.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Describe Amp as opt-in managed support

This now says Amp is “not managed”, but the harness registry has Amp skill inspection/setup and MCP support, and setup accepts --agents=amp, so Amp users are steered away from an existing opt-in managed path for skills/MCP. If Amp is not a default target, this should say compat/opt-in rather than unmanaged; OpenCode and OpenClaw can remain compatibility-only.

Useful? React with 👍 / 👎.