Finalize v0.1.0 release prerequisites

Author: xiwuqi

CHANGELOG.md

@@ -4,20 +4,11 @@ All notable changes to ContextForge will be documented in this file.
 
 ## Unreleased
 
-### Release-candidate scope
+- No unreleased changes tracked yet.
+- The `0.1.0` entry below reflects the prepared release contents. GitHub Release creation and npm publish still happen only after the maintainer dispatches the release workflow successfully.
 
-- Local-first CLI for repository scan/init, task-pack compilation from markdown or GitHub issue sources, and task-brief exports for Codex, Claude Code, and Cursor.
-- Packaged CLI smoke validation, deterministic fixture evals, and release-candidate maintainer checks.
-- Checked-in demo artifacts under `examples/demo/` for first-time readers.
-- Manual publish dry-run and package-content sanity checks for first npm release preparation.
-- Bootstrap-era root PRD archived under `docs/archive/bootstrap/` so `docs/product/` stays the public source of truth.
-- Versioned release artifact bundles under `.contextforge/releases/<version>/` for manual release handoff.
-- English and Simplified Chinese READMEs plus lightweight SVG diagrams for first-visit onboarding.
-- Internal milestone Codex prompts archived out of `.github/codex/prompts/` so the default Codex output directory stays clean.
-- GitHub issue and pull request templates plus lightweight contributing, security, and triage docs for early external users.
-- Manual-dispatch release automation for repo metadata sync, GitHub Release creation, npm publish, and post-release verification.
+## 0.1.0
 
-### Notes
-
-- No npm package has been published from this changelog yet.
-- Version selection and changelog readiness remain explicit maintainer decisions before any workflow dispatch.
+- Local-first CLI for repository scan/init, task-pack compilation from markdown or GitHub issue sources, and compact exports for Codex, Claude Code, and Cursor.
+- Stale-context linting plus deterministic fixture evals, packaged smoke validation, publish dry-run, and release-candidate checks.
+- Checked-in demo assets, bilingual README onboarding, community contribution templates, and manual-dispatch release automation for the first public release path.

docs/maintainers/first-public-release-checklist.md

@@ -25,10 +25,18 @@ Recommended defaults for a normal public release:
 - `sync_repo_metadata`: `true`
 - `prerelease`: `false`
 
+For the first live public release, use these exact values:
+
+- `version = 0.1.0`
+- `npm_tag = latest`
+- `publish_to_npm = true`
+- `create_github_release = true`
+- `sync_repo_metadata = true`
+- `prerelease = false`
+
 ## After the workflow finishes
 
 - verify the GitHub Release exists and includes the tarball plus checksums
 - verify the npm package page shows the expected version and README
 - review GitHub About text, topics, and homepage
 - spot-check the install and quickstart flow from the published package
-

docs/maintainers/first-public-release.md

@@ -2,7 +2,7 @@
 
 Use this guide when ContextForge is ready for its first public release candidate or first published release.
 
-If you want the shortest actionable list, start with `docs/maintainers/first-public-release-checklist.md`. Use this document for the surrounding context and decision points.
+If you want the shortest actionable list, start with `docs/maintainers/first-public-release-checklist.md`. Use `docs/maintainers/live-release-prerequisites.md` for the exact first live dispatch values and external setup. Use this document for the surrounding context and decision points.
 
 ## What should already be true
 
@@ -40,6 +40,15 @@ npm run release:artifacts
 
 When the version, changelog, permissions, and npm setup are ready, trigger the release workflow in GitHub Actions instead of recreating the publish steps by hand.
 
+For the first live public release, the recommended workflow-dispatch values are:
+
+- `version = 0.1.0`
+- `npm_tag = latest`
+- `publish_to_npm = true`
+- `create_github_release = true`
+- `sync_repo_metadata = true`
+- `prerelease = false`
+
 ## Inspect the demo assets
 
 Review the files in `examples/demo/` before publishing:

docs/maintainers/live-release-prerequisites.md

@@ -0,0 +1,38 @@
+# Live release prerequisites
+
+Use this before triggering `.github/workflows/release.yml` for the first real public release.
+
+## External setup required
+
+- GitHub Actions workflow permissions must allow read and write access so `github.token` can create tags and GitHub Releases.
+- `REPO_METADATA_TOKEN` is needed if you want the workflow to sync repository description, homepage, and topics.
+  - Reason: editing repo metadata usually needs broader repo settings permission than `github.token` provides.
+- npm trusted publishing should be configured for this repository if you want tokenless publish from GitHub Actions.
+- If npm trusted publishing is not configured, create the repository secret `NPM_TOKEN` as the fallback publish credential.
+
+## First live dispatch values
+
+For the first public release, use:
+
+- `version = 0.1.0`
+- `npm_tag = latest`
+- `publish_to_npm = true`
+- `create_github_release = true`
+- `sync_repo_metadata = true`
+- `prerelease = false`
+
+## Before dispatch
+
+- `CHANGELOG.md` contains the `0.1.0` entry.
+- `package.json` version is `0.1.0`.
+- `npm run release:check` passes locally.
+- `npm run release:artifacts` has generated the current bundle under `.contextforge/releases/0.1.0/`.
+- `.github/release/repo-metadata.json` matches the intended public metadata.
+
+## After the workflow finishes
+
+- verify the GitHub Release exists and includes the tarball plus checksums
+- verify the published npm version is `0.1.0`
+- verify the npm package page renders the README and links correctly
+- verify GitHub About text, homepage, and topics match `.github/release/repo-metadata.json`
+

docs/maintainers/manual-release-handoff.md

@@ -43,7 +43,7 @@ Check that it:
 After reviewing the bundle:
 
 1. make sure `.github/release/repo-metadata.json`, `package.json`, and `CHANGELOG.md` are ready in git
-2. confirm the release workflow permissions and secrets described in `docs/maintainers/release-automation.md`
+2. confirm the release workflow permissions and secrets described in `docs/maintainers/release-automation.md` and `docs/maintainers/live-release-prerequisites.md`
 3. trigger the manual-dispatch release workflow
 4. if metadata sync or npm publish credentials are not configured, complete only those missing steps manually
 5. verify the GitHub Release and npm package page after publish

docs/maintainers/npm-publish-guide.md

@@ -28,6 +28,12 @@ If trusted publishing is not available yet:
 
 The workflow will then publish using token auth instead of trusted publishing.
 
+For the first live public release, keep these workflow inputs:
+
+- `version = 0.1.0`
+- `npm_tag = latest`
+- `publish_to_npm = true`
+
 ## Safety notes
 
 - never print or commit npm tokens
@@ -42,4 +48,3 @@ After the workflow publishes:
 - confirm `npm view contextforge@<version> version` returns the expected version
 - verify the npm package page renders `README.md` correctly
 - verify homepage, repository, bugs, and license links
-

docs/maintainers/release-automation.md

@@ -4,6 +4,8 @@ ContextForge ships a manual-dispatch release workflow at `.github/workflows/rele
 
 It does not run on push. A maintainer must dispatch it explicitly with the target version.
 
+For the first live public release, see `docs/maintainers/live-release-prerequisites.md` for the exact dispatch values and required external setup.
+
 ## What the workflow does
 
 When configured correctly, the workflow:
@@ -59,10 +61,18 @@ Secrets:
 4. dispatch the workflow with the matching version
 5. review the GitHub Release and npm package page after it finishes
 
+Recommended first live dispatch:
+
+- `version = 0.1.0`
+- `npm_tag = latest`
+- `publish_to_npm = true`
+- `create_github_release = true`
+- `sync_repo_metadata = true`
+- `prerelease = false`
+
 ## What remains outside repo automation
 
 - deciding the version to release
 - writing or curating final changelog content
 - configuring GitHub workflow permissions
 - configuring repo metadata token or npm publishing setup
-

docs/maintainers/release-checklist.md

@@ -67,6 +67,7 @@ Before a first public release, review:
 - `docs/maintainers/public-metadata-checklist.md`
 - `docs/maintainers/manual-release-handoff.md`
 - `docs/maintainers/release-automation.md`
+- `docs/maintainers/live-release-prerequisites.md`
 - `docs/maintainers/npm-publish-guide.md`
 
 ## Manual publish boundary