docs: release v1.0.0 — one plugin, a packaged install, and semantic versioning

[mauricios]

What changed and why

The first numbered release, v1.0.0 (decision 0017). It's a major release because the installer plugin is renamed aplyca-adf.

• CHANGELOG.md: Unreleased becomes ## v1.0.0 — 2026-10-02 — One plugin, a packaged install, and semantic versioning, covering fix: /upgrade carries the uncommitted plugin setting into the hub's worktree #17–feat!: one plugin, aplyca-adf, with a packaged install, and semantic versioning (decisions 0016, 0017) #20 and the install fix below. It opens with the order to upgrade from 7383422:
  1. Install aplyca-adf with the install prompt.
  2. Run /aplyca-adf:upgrade. It renames the setting, pins v1.0.0, and restamps.
  3. Uninstall aplyca-framework.
• plugin.json is already 1.0.0. The static check now has a ## v heading to match it against, and it passes.
• README § Update a project described the framework as copied in, called 7383422 the latest release, and had an update command without --scope. It now covers moving from release to release, the pin, and the old name.
• docs/UPGRADING.md:
  • The target is the newest tag, not main.
  • The stamp and the commit message carry the version.
  • A new scenario covers projects adopted before v1.0.0.
• The plugin README's update section told projects adopted before v1.0.0 to plugin update aplyca-adf, which they never installed. It now sends them to the install prompt.

A fix the migration needed: the install refreshes a marketplace added before

A machine that added the aplyca marketplace before #20 keeps its copy, which lists only aplyca-framework. claude plugin marketplace add leaves that copy alone. So the install prompt failed with Plugin "aplyca-adf" not found in every project adopted before this release, which is step 1 of the upgrade order. The prompt, ADOPT.md, and the documented commands now run claude plugin marketplace update aplyca before the install. It's a separate commit with its own changelog entry.

Upgrade impact

Nothing new for adopting projects beyond the entries being released. The install fix is framework-internal.

How to verify

1. ./evals/run-evals.sh: the version check matches 1.0.0 against the heading, and a new practices check covers the refresh in the install prompt.
2. Read the v1.0.0 heading's upgrade order against what /aplyca-adf:upgrade does.

Verified / not verified

• Verified:
  • Static suites pass: 153, 75, 45, and 11.
  • The install bug and its fix, on an isolated plugin cache. I reset a copy of the marketplace to cbfe5fd, the 7383422 release. Re-running marketplace add left it there, and plugin install aplyca-adf@aplyca failed as "not found". After marketplace update aplyca, it moved to 9958c51 and the install succeeded at project scope. Your own plugin state was checked unchanged.
• Not verified:
  • A project pinned to the v1.0.0 tag. The tag doesn't exist until this merges.
  • The full migration in a real project. The marketing-site pilot is the first.

Merge danger

• Docs and the install commands only. A revert undoes it cleanly.
• The tag comes right after the merge. Upgrading writes "ref": "v1.0.0" into projects, and that pin fails until the tag v1.0.0 exists on the merge commit. Push the tag before anyone runs /aplyca-adf:upgrade.

🤖 Generated with Claude Code