docs(adapters): add external-adapter discovery index + authoring guide

docs/adapters/authoring.md

@@ -0,0 +1,84 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Authoring an adapter](#authoring-an-adapter)
+  - [Two homes for an adapter](#two-homes-for-an-adapter)
+  - [Authoring a tool adapter](#authoring-a-tool-adapter)
+  - [Authoring an organization](#authoring-an-organization)
+  - [After authoring](#after-authoring)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+     https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Authoring an adapter
+
+When Magpie ships no [adapter](../vendor-neutrality.md#tool-adapters) for
+your backend — a forge, a CNA tool, a chat system, a mail archive, a VCS,
+or a whole [organization](../../organizations/README.md) profile — you
+author one. The skills stay agnostic: they target a *capability*, and
+your adapter supplies the concrete backend. This guide is the how-to; the
+[registry](registry.md) is the index of what already exists.
+
+## Two homes for an adapter
+
+| | Contribute to Magpie | Keep it external |
+|---|---|---|
+| **Where it lives** | a PR into `apache/magpie` | your own repository |
+| **License** | Apache-2.0 ([§17](../../PRINCIPLES.md#17-contributions-land-under-apache-license-20)) | yours |
+| **Who reuses it** | every adopter on that backend | you (and anyone you share it with) |
+| **Discovery** | shipped in-tree | optionally listed in the [registry](registry.md) |
+| **Install** | part of the snapshot | you wire it in deliberately — never auto-fetched ([§13](../../PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies)) |
+
+Both are first-class. Contributing upstream is preferred when the backend
+is one other projects share; an external adapter is right when it is
+specific to you or you are not ready to upstream.
+
+## Authoring a tool adapter
+
+A tool adapter fulfils a capability *contract* for one backend.
+
+1. **Find the contract.** Pick the `tools/<contract>/` whose capability
+   you are implementing (e.g. [`tools/cve-tool/`](../../tools/cve-tool/)
+   for a CNA tool, [`tools/mail-archive/`](../../tools/mail-archive/) for
+   an archive). Its README enumerates the methods/verbs your adapter must
+   provide. If no contract exists for the capability, propose one first.
+2. **Create the adapter directory** — `tools/<contract>-<backend>/` (in
+   tree) or a directory in your own repo (external). Implement the
+   contract's operations.
+3. **Declare the metadata** the validator requires (see
+   [`tools/AGENTS.md`](../../tools/AGENTS.md)):
+   - a `**Capability:** capability:NAME` line in the README;
+   - a `## Prerequisites` section (runtime, CLIs, credentials, network);
+   - optionally an `**Organization:** <org>` line if the adapter belongs
+     to a specific organization.
+4. **Wire it in.** Point your `<project-config>/project.md` *Tools
+   enabled* manifest (or the relevant capability key, e.g.
+   `cve_authority.tool`) at the adapter. Skill bodies never change.
+5. **Add an eval** ([§8](../../PRINCIPLES.md#8-eval-is-a-release-blocking-discipline))
+   under `tools/skill-evals/evals/` so the adapter's behaviour is graded,
+   not just demoed.
+
+The [`write-skill`](../../skills/write-skill/SKILL.md) flow and
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md) walk the conventions in detail;
+`skill-and-tool-validate` enforces the capability + prerequisites lines.
+
+## Authoring an organization
+
+An organization groups governance vocabulary + capability→adapter
+selections + identity for every project under one governing body. To add
+one, copy [`organizations/_template/`](../../organizations/_template/) to
+`organizations/<org>/`, fill in `organization.md` (identity incl. `logo`,
+governance vocabulary, and the backend bundle), and point projects at it
+with `organization: <org>`. See
+[`organizations/README.md`](../../organizations/README.md).
+
+## After authoring
+
+- **Contributing upstream?** Open the PR; once it merges and adopters run
+  `/magpie-setup upgrade`, the adapter is available to everyone.
+- **Keeping it external?** Optionally add a row to the
+  [registry](registry.md#community--external-adapters) so others can
+  discover it — discovery only, no install.

docs/adapters/registry.md

@@ -0,0 +1,84 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Adapter registry](#adapter-registry)
+  - [In-tree tool adapters](#in-tree-tool-adapters)
+  - [In-tree organizations](#in-tree-organizations)
+  - [Community / external adapters](#community--external-adapters)
+    - [Adding an external adapter to this index](#adding-an-external-adapter-to-this-index)
+  - [See also](#see-also)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+     https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Adapter registry
+
+A **discovery** index of the [tool adapters](../vendor-neutrality.md#tool-adapters)
+and [organizations](../../organizations/README.md) Magpie knows about —
+the ones that ship in-tree, the open extension points, and links to
+**community-maintained adapters defined elsewhere**.
+
+> **Discovery, never installation.** Per
+> [`PRINCIPLES.md` §13](../../PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies),
+> this page is an index, not a package manager. Nothing here is
+> auto-fetched. To use an adapter you wire it in deliberately — point
+> your `<project-config>/project.md` (or `organizations/<org>/`) at it,
+> exactly as you would a built-in one. An external link is a pointer for
+> humans to evaluate, not a supply-chain hook.
+
+To author a new adapter, see [`authoring.md`](authoring.md).
+
+## In-tree tool adapters
+
+Each capability contract under `tools/<contract>/` enumerates the
+adapters that fulfil it. Shipping = a working adapter in the tree;
+extension point = a documented, labelled slot with a tracking issue.
+
+| Capability contract | Shipping adapter(s) | Extension points (tracked) |
+|---|---|---|
+| [`tools/cve-tool`](../../tools/cve-tool/) | [`cve-tool-vulnogram`](../../tools/cve-tool-vulnogram/) (ASF) | MITRE form, CVE.org direct, GHSA |
+| [`tools/mail-archive`](../../tools/mail-archive/) | [`ponymail`](../../tools/ponymail/) (ASF) | Hyperkitty, Discourse, Google Groups, GitHub Discussions |
+| [`tools/mail-source`](../../tools/mail-source/) | mbox, IMAP | Mailman 3 ([#306](https://github.com/apache/magpie/issues/306)) |
+| [`tools/forwarder-relay`](../../tools/forwarder-relay/) | ASF-security ([`tools/gmail/asf-relay.md`](../../tools/gmail/asf-relay.md)) | huntr.com, HackerOne, GHSA relay |
+| [`tools/scan-format`](../../tools/scan-format/) | ASVS | other scanner formats |
+| [`tools/vcs`](../../tools/vcs/) | Git | Mercurial [#601](https://github.com/apache/magpie/issues/601), Subversion [#602](https://github.com/apache/magpie/issues/602), Jujutsu [#603](https://github.com/apache/magpie/issues/603), Fossil [#604](https://github.com/apache/magpie/issues/604), Perforce [#605](https://github.com/apache/magpie/issues/605) |
+| Forge / tracker | [`github`](../../tools/github/), [`jira`](../../tools/jira/) | GitLab [#305](https://github.com/apache/magpie/issues/305), Forgejo/Gitea [#310](https://github.com/apache/magpie/issues/310), Pagure [#312](https://github.com/apache/magpie/issues/312), Bitbucket [#606](https://github.com/apache/magpie/issues/606), SourceHut [#607](https://github.com/apache/magpie/issues/607), Bugzilla [#302](https://github.com/apache/magpie/issues/302) |
+| Agentic runtime | Claude Code | Codex [#313](https://github.com/apache/magpie/issues/313)–OpenHands [#322](https://github.com/apache/magpie/issues/322) |
+| Security cross-ref | — | OSV.dev [#311](https://github.com/apache/magpie/issues/311) |
+
+## In-tree organizations
+
+| Organization | Directory |
+|---|---|
+| Apache Software Foundation | [`organizations/ASF/`](../../organizations/ASF/) |
+| Independent (no formal governing body) | [`organizations/independent/`](../../organizations/independent/) |
+
+## Community / external adapters
+
+Adapters maintained **outside** this repository — kept in their authors'
+own repos and linked here for discovery. An adopter wires one in by
+pointing their config at it (see the discovery-not-installation note
+above); the framework never fetches them.
+
+| Adapter | Capability / org | Maintainer | Link | Notes |
+|---|---|---|---|---|
+| *(none listed yet)* | | | | Open a PR to add a row — see below. |
+
+### Adding an external adapter to this index
+
+Open a PR against `apache/magpie` that adds one row to the table above
+with: the adapter name, the capability contract (or organization) it
+implements, the maintainer, a link to its repository, and a one-line
+note. Listing here is **editorial discovery only** — it makes no
+guarantee about the adapter and triggers no install. Adapters you would
+rather contribute into the tree itself follow [`authoring.md`](authoring.md)
+instead.
+
+## See also
+
+- [`docs/vendor-neutrality.md`](../vendor-neutrality.md) — how tool adapters and organizations deliver neutrality.
+- [`authoring.md`](authoring.md) — authoring your own adapter.
+- [`organizations/README.md`](../../organizations/README.md) — the organization entity.

docs/index.md

@@ -120,6 +120,7 @@ from mailing lists, slack etc.
 |---|---|
 | Understand the full vision | [MISSION.md](../MISSION.md) |
 | Understand how it stays vendor-neutral | [vendor-neutrality.md](vendor-neutrality.md) |
+| Find or author a backend adapter | [adapters/registry.md](adapters/registry.md) |
 | See what skills exist today | [modes.md](modes.md) |
 | Adopt in my project | [README → Adopting](../README.md#adopting-the-framework) |
 | Set up the secure agent sandbox | [setup/](setup/README.md) |

docs/vendor-neutrality.md

@@ -248,11 +248,13 @@ organization profile — you author one, and you have two supported paths:
   so every other adopter on that backend reuses your work. The
   [`write-skill`](../skills/write-skill/SKILL.md) flow and
   [`CONTRIBUTING.md`](../CONTRIBUTING.md) walk you through the conventions
-  (a `**Capability:**` line, a `## Prerequisites` section, an eval).
+  (a `**Capability:**` line, a `## Prerequisites` section, an eval); the
+  step-by-step how-to is [`docs/adapters/authoring.md`](adapters/authoring.md).
 - **Link to an adapter defined elsewhere.** You do not have to upstream
   it. Keep the adapter in your own repository and point your project or
-  organization config at it. The framework curates a discovery index of
-  in-tree and community-maintained adapters — but, per
+  organization config at it. The framework curates a
+  [discovery index](adapters/registry.md) of in-tree and
+  community-maintained adapters — but, per
   [`PRINCIPLES.md` §13](../PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies),
   an index is **for discovery, never for installation**: nothing is
   auto-fetched, and you wire an external adapter in deliberately, exactly

organizations/README.md

@@ -97,4 +97,5 @@ governance vocabulary and the capability→adapter bundle, and point your
 project at it with `organization: <org>`. You can then either
 **contribute it back** to `apache/magpie` under Apache-2.0 (so other
 projects in your organization reuse it) or keep it local. See
-[`docs/vendor-neutrality.md` § Authoring your own adapter](../docs/vendor-neutrality.md#authoring-your-own-adapter).
+[`docs/adapters/authoring.md`](../docs/adapters/authoring.md) (and
+[`docs/vendor-neutrality.md` § Authoring your own adapter](../docs/vendor-neutrality.md#authoring-your-own-adapter)).