fix(kyberforge): bridge apm content to Claude Code's flat plugin discovery

Claude Code's (and Copilot's) native plugin installer has zero awareness of
.apm/ nesting -- it convention-scans only flat skills/, agents/, commands/,
hooks.json at each plugin's root. Confirmed via strings on the installed
claude binary and live installs of git@holocron/gitea@holocron/kyberforge@
holocron, all reporting Skills(0) Agents(0) Hooks(0) post ADR-0015's apm
conversion. Root cause (apm_cli/core/plugin_manifest.py): apm's plugin.json
compiler deliberately strips skills/agents/commands keys, assuming the host
already auto-discovers those convention directories -- it has no model of
.apm/ being host-visible at all. Separately, apm's own bundle exporter
(apm_cli/bundle/plugin_exporter.py, behind `apm pack --format plugin`)
implements the correct .apm/ -> flat mapping, but only ever targeted
build/<name>-<version>/, a path nothing in marketplace.json's source: points
at.

scripts/sync-plugin-content.sh wraps that bundle exporter and copies its
agents/, skills/, commands/, instructions/, extensions/, and merged
hooks.json back into each plugin's own root as a second tracked
compiled-output category -- same governance status as
.claude-plugin/plugin.json: generated from .apm/, never hand-edited. tests/
subdirectories are excluded from the mirror (dev fixtures, not host-visible
runtime content; several hardcode a relative repo-root walk-up sized for the
.apm/-nested depth, which breaks when duplicated one level shallower).
Applied for real across all 6 plugins and verified two ways: `claude plugin
validate --strict` passes on every real plugin directory, and a live
`claude --plugin-dir <path> -p "list skills/agents"` behavioral test
confirms content is now actually discovered.

Also, from the same issue #90 review round:
- scripts/check-manifests.sh pointed at each plugin's root-level plugin.json
  (checking skills/hooks/mcpServers/agents pointer fields) -- that file was a
  stale near-duplicate of .claude-plugin/plugin.json nothing else read or
  wrote, now deleted across all 6 plugins. check-manifests.sh is rewritten to
  validate .claude-plugin/plugin.json instead, and drops the pointer-field
  checks entirely (nothing to check -- those fields are correctly absent by
  design). Content-presence drift is now check-plugin-content-sync's job, a
  new pre-push hook wired in .pre-commit-config.yaml.

docs/adr/0017 records the root cause and decision in full, including two
rejected alternatives (patching plugin.json's path fields directly -- apm's
compiler strips them on every run; pointing marketplace.json at apm pack's
build/ output -- a version-suffixed non-source directory nothing can install
from without an extra build step). ADR-0015 and CONTEXT.md are updated to
point at it.

Refs: #90

plugins/gitea/skills/gitea-releases/references/call-signatures.md

@@ -0,0 +1,75 @@
+---
+topic: call-signatures
+source_keys:
+  - gitea-mcp-repo
+  - gitea-mcp-slim-go
+---
+
+# Release and tag call signatures
+
+Signatures and response shapes are derived from gitea-mcp source (`operation/*.go` and `slim.go`,
+see `references/sources.md`) rather than copied from upstream API docs, which can drift from the
+deployed gitea-mcp version — but this is a source-code extraction, not a live MCP tool call.
+
+Input parameter schemas for 3 of the 9 tools here — `create_release`, `delete_tag`, and
+`get_latest_release` — were additionally cross-checked live via `ToolSearch` against the deployed
+`mcp__gitea__*` tools in session 2026-07-05, and confirmed to match exactly (required/optional
+params and names). That check covered only input params for those 3 tools, not response shapes,
+and not the other 6 tools — treat the rest of this document as source-derived, not live-verified.
+
+`owner` and `repo` are required strings on every tool below and are omitted from the per-tool lists
+for brevity.
+
+## Releases
+
+**`list_releases`**
+- Optional: `is_draft` (boolean), `is_pre_release` (boolean), `page` (number, default 1), `per_page` (number, default 20)
+- Returns an array of release objects (shape below), one page at a time.
+
+**`get_release`**
+- Required: `id` (number) — the release's numeric id, not its tag name.
+- Returns a single release object.
+
+**`get_latest_release`**
+- No parameters beyond `owner`/`repo`.
+- Returns a single release object for the most recently published release. It is assumed (by analogy with typical "latest release" semantics) that this excludes drafts and prereleases, but that exclusion is not directly confirmed by any of the research docs — verify with `list_releases` if the caller depends on this.
+
+**`create_release`**
+- Required: `tag_name` (string), `target` (string — branch, tag, or commit SHA to cut the tag from), `title` (string)
+- Optional: `body` (string — release notes), `is_draft` (boolean), `is_pre_release` (boolean)
+- Assumed (not confirmed by the research docs) that if `tag_name` doesn't already exist as a tag, Gitea creates it against `target` as part of this call. Verify with `get_tag`/`list_tags` afterward if the caller needs certainty.
+
+**`delete_release`**
+- Required: `id` (number) — same numeric id as `get_release`. Does not accept `tag_name`.
+- Does not delete the underlying tag.
+
+**Release object shape** (returned by list/get/create/latest):
+```
+id, tag_name, target, title, body, draft, prerelease, html_url, author, created_at, published_at
+```
+`author` is the creator's login. `body` holds the release notes.
+
+## Tags
+
+**`list_tags`**
+- Optional: `page` (number, default 1), `per_page` (number, default 20)
+- Returns an array of `{ name, commit_sha }` — no `message` field on list responses.
+
+**`get_tag`**
+- Required: `tag_name` (string)
+- Returns `{ name, message, commit_sha }` — the only tag call that returns `message`.
+
+**`create_tag`**
+- Required: `tag_name` (string)
+- Optional: `target` (string — commitish to tag; if omitted, Gitea tags the default branch tip), `message` (string — annotated tag message)
+
+**`delete_tag`**
+- Required: `tag_name` (string). Does not accept a numeric id.
+- Assumed by symmetry with `delete_release` (documented above as not deleting the underlying tag) to also not delete any release wrapping the tag — but this reverse direction is not independently confirmed by the research docs, and is the more dangerous direction to get wrong: an agent might skip an explicit `delete_release` call assuming the release survives. Verify with `list_releases`/`get_release` after calling `delete_tag` rather than assume.
+
+## Pagination
+
+None of the list tools auto-paginate. To collect a full result set, call with `page: 1`, then
+`page: 2`, etc., stopping when a page returns fewer items than `per_page`. `list_releases` and
+`list_tags` default `per_page` to 20 — lower than the 30-default used by most other gitea-mcp list
+tools, so a caller assuming 30 will under-count pages needed for a fixed total.

plugins/gitea/skills/gitea-releases/references/conventions.md

@@ -0,0 +1,44 @@
+---
+topic: conventions
+source_keys:
+  - context7-websites-gitea
+  - context7-gitea-tea-cli
+---
+
+# Release and tag conventions
+
+Practitioner conventions that inform *how* to use the mechanics in `call-signatures.md` — not
+additional tool schemas.
+
+## Release wraps a tag, not the reverse
+
+A release is a title, body (notes), and draft/prerelease flags layered on top of an existing or
+newly-created tag. The tag is the git-level object (a name pointing at a commit); the release is a
+Gitea-level metadata wrapper around it. This is why `delete_release` and `delete_tag` are separate
+calls with separate identifiers (numeric id vs. tag name) — removing the wrapper never implies
+removing the underlying pointer, and vice versa.
+
+## Semver tag naming
+
+Per the `tea` CLI (the reference Gitea client), tag names conventionally follow semver with a `v`
+prefix: `v1.2.0`, `v2.0.0-beta.1`. This is a convention observed by tooling and humans, not a
+Gitea-enforced constraint — the API accepts any string as `tag_name`. Don't validate or rewrite a
+caller-supplied tag name against semver; just pass it through.
+
+## Draft and prerelease are explicit flags
+
+`is_draft` and `is_pre_release` are booleans the caller sets directly on `create_release` — Gitea
+does not infer either from the tag name, even though the `-beta`/`-rc` suffix convention above is
+commonly used to signal a prerelease to humans. When a user asks to "cut a beta" or "publish a
+release candidate," set `is_pre_release: true` explicitly in the same call rather than relying on
+the tag string to carry that meaning.
+
+Note the input/output naming mismatch: the input param is `is_draft`, but the release object
+returned by the API uses `draft` (and `prerelease`) as the field names. `draft` is never a valid
+input key — passing `draft: true` to `create_release` is silently ignored rather than erroring.
+
+## Release notes sourcing
+
+Practitioner convention (per `tea`) is to source release notes (`body`) from a changelog file
+rather than typing them inline for each release — useful context when a caller asks to "generate"
+or "use the changelog for" release notes rather than write them from scratch.

plugins/gitea/skills/gitea-releases/references/sources.md

@@ -0,0 +1,48 @@
+# Sources
+
+## gitea-mcp-repo
+
+- **URL:** https://gitea.com/gitea/gitea-mcp
+- **Description:** Official gitea-mcp repository (v1.3.0); operation/*.go source files documenting all 55 MCP tools, their parameters, and CLI flags.
+- **Research doc:** plugins/gitea/docs/research/docs/gitea/api-reference.md (Releases and Tags section); plugins/gitea/docs/research/docs/gitea/troubleshooting.md (`delete_release` numeric-id gotcha, `per_page` defaults)
+
+**Contributing files:**
+- SKILL.md (Dispatch table, Gotchas)
+- references/call-signatures.md
+
+**Status:** `extracted`
+
+## gitea-mcp-slim-go
+
+- **URL:** https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/repo/slim.go
+- **Description:** Slim response shape structs from gitea-mcp source; defines exactly which fields the MCP server returns for tags and releases.
+- **Research doc:** plugins/gitea/docs/research/docs/gitea/api-reference.md (Releases and Tags response shapes)
+
+**Contributing files:**
+- references/call-signatures.md (release/tag object shapes)
+
+**Status:** `extracted`
+
+## context7-websites-gitea
+
+- **URL:** context7:/websites/gitea
+- **Description:** Official Gitea docs mirror on Context7 (docs.gitea.com content) — release and tag semantics, draft/prerelease behavior.
+- **Research doc:** plugins/gitea/docs/research/docs/gitea/workflow-conventions.md (Release and tag conventions section)
+
+**Contributing files:**
+- SKILL.md (Gotchas — draft/prerelease as explicit flags)
+- references/conventions.md
+
+**Status:** `extracted`
+
+## context7-gitea-tea-cli
+
+- **URL:** context7:/git_gitea_com/gitea_tea
+- **Description:** Official `tea` CLI (reference Gitea client) docs on Context7 — practitioner release/tag command patterns, semver tag conventions, draft/prerelease flags, release-notes-from-file conventions.
+- **Research doc:** plugins/gitea/docs/research/docs/gitea/workflow-conventions.md (Release and tag conventions section)
+
+**Contributing files:**
+- SKILL.md (Gotchas — semver tag naming)
+- references/conventions.md
+
+**Status:** `extracted`