Skip to content

docs: reconcile v0.12.3 launch surfaces #59

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TheAmericanMaker merged 1 commit into from
Jul 23, 2026
Merged

docs: reconcile v0.12.3 launch surfaces #59

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This document tracks future-facing work. For the current shipped surface, see [README.md](../README.md).

## Where We Are (v0.12.2)
## Where We Are (v0.12.3)

Already shipped:

Expand All @@ -29,7 +29,7 @@ Open future-facing items:

### Launch proof package (active)

The v0.12.2 npm, GitHub, website, and official MCP Registry release gates are
The v0.12.3 npm, GitHub, website, and official MCP Registry release gates are
complete. The next launch milestone is durable, inspectable proof before any
short-lived promotional channel:

Expand Down
63 changes: 33 additions & 30 deletions docs/plans/2026-07-21-v0.12.1-discoverability-launch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# v0.12.x discoverability and launch plan

Date: 2026-07-21
Last reconciled: 2026-07-22
Last reconciled: 2026-07-23
Status: active — release and Registry gates complete; proof package next
Owner: maintainer, unless reassigned below

Expand All @@ -11,9 +11,11 @@ Ship a small, truthful discoverability release that makes CodeCartographer
discoverable as both an evidence-backed reverse-engineering tool and a
human-gated software-planning tool. v0.12.1 delivered the storefront and package
metadata; v0.12.2 corrected the case-sensitive GitHub organization namespace and
became the version published to the official MCP Registry. Support that
positioning with inspectable case studies, and only then use short-lived launch
channels to amplify the durable assets.
became the first version published to the official MCP Registry. v0.12.3 fixed
single-shot `/codecarto-next` phase completion and is the current release across
npm, GitHub, the website, and the Registry. Support that positioning with
inspectable case studies, and only then use short-lived launch channels to
amplify the durable assets.

The launch is successful when a new user can discover CodeCartographer, install
the published package, understand both directions of the workflow, inspect real
Expand Down Expand Up @@ -42,13 +44,13 @@ Checked on 2026-07-21:
- The current working branch is `release/v0.12.0`; v0.12.1 work should begin on
a fresh branch from the latest `origin/main`.

## Reconciled status — 2026-07-22
## Reconciled status — 2026-07-23

- **Gate 1 passed.** v0.12.2 is published on npm and GitHub, the public-package
MCP smoke test passes 9/9, and GitHub Pages built the matching website commit.
- **Gate 2 passed.** The official Registry API returns one active, latest entry
for `io.github.HuginnIndustries/codecartographer` v0.12.2 with the expected npm
package and stdio transport.
- **Gate 1 passed.** v0.12.3 is published on npm and GitHub, the full seven-phase
smoke test passes, and GitHub Pages built the matching website commit.
- **Gate 2 passed.** The official Registry API marks
`io.github.HuginnIndustries/codecartographer` v0.12.3 active and latest with the
expected npm package and stdio transport.
- **Gate 3 is next.** The self-analysis and forward-synthesis case studies,
screenshots, and concise walkthrough remain open.
- **Gate 4 remains pending.** Channel drafts and submissions wait on Gate 3 and
Expand Down Expand Up @@ -81,7 +83,7 @@ Review after 24 hours,
| --- | --- | --- |
| Release truth | Public npm, GitHub Release, `main`, and website agree on version and positioning | 100% |
| Installability | Clean Node 22 and 24 smoke tests pass against the published package | 2/2 |
| MCP discovery | Registry API returns the expected server name and v0.12.2 package | indexed |
| MCP discovery | Registry API returns the expected server name and marks v0.12.3 latest | indexed |
| Proof | At least one analysis case and the forward-synthesis case are inspectable before Show HN | 2 cases |
| Activation | Visitors can reach an install command or runnable demo in two clicks or fewer | pass |
| Useful response | Issues, discussions, or comments contain concrete use cases or technical feedback | qualitative |
Expand Down Expand Up @@ -111,15 +113,15 @@ run in parallel with the release PR, but must close before their later gates.
that the Product Hunt account is old enough to submit. Product Hunt may
impose a one-week wait on a new account.
- [x] Confirm access to the separate `HuginnIndustries/CodeCartographer-Website`
checkout and remote. v0.12.2 is deployed from `main` at the repository root
checkout and remote. v0.12.3 is deployed from `main` at the repository root
through GitHub Pages with the `codecarto.dev` custom domain.
- [x] Keep the patch releases focused on discoverability and Registry metadata;
automate Registry publication only after the first successful manual
publish.

**Gate 0 passes when:** every item has a named answer in the release issue or PR.

## Workstream A — Ship v0.12.1 and the v0.12.2 Registry correction
## Workstream A — Ship the v0.12.x discoverability patches

### A1. Start from the public release state

Expand Down Expand Up @@ -152,7 +154,7 @@ Update `package.json` and `package-lock.json` together:
- [x] Describe CodeCartographer as a local stdio server; do not claim a hosted
transport.
- [x] Point the npm package to the matching release version and use stdio
transport. v0.12.2 is the final published Registry version.
transport. v0.12.3 is the current published Registry version.
- [x] Omit environment variables because the server does not require secrets.
- [x] Use the canonical GitHub repository URL.
- [x] Keep the schema URL generated by the current publisher instead of copying
Expand Down Expand Up @@ -224,12 +226,12 @@ npm run demo:synthesis
- [x] Require green Node 22 and 24 CI.
- [x] Merge each release PR before creating its tag.

Local and CI verification through 2026-07-22:
Local and CI verification through 2026-07-23:

- Build passed.
- Full suite passed: 263/263 tests.
- Official MCP schema validation passed.
- Package dry run and tarball inspection passed; the v0.12.2 manifest contains
- Package dry run and tarball inspection passed; the v0.12.3 manifest contains
the exact-case `mcpName`, description, keywords, and binary.
- Packed-tarball MCP smoke passed: 9/9 assertions.
- Synthesis demo generation passed.
Expand All @@ -239,20 +241,20 @@ Local and CI verification through 2026-07-22:

### A7. Publish and verify

- [x] Tag the merged v0.12.1 and v0.12.2 commits and let the existing release
workflow publish npm and GitHub Release artifacts.
- [x] Tag the merged v0.12.1, v0.12.2, and v0.12.3 commits and let the existing
release workflow publish npm and GitHub Release artifacts.
- [x] Verify npm returns the expected version, description, keywords, `mcpName`,
repository, binary, and provenance.
- [x] Run the equivalent smoke test against public
`codecartographer-pi@0.12.2`, not the local tarball; all 9 checks pass.
- [x] Run the published-package MCP smoke test (9/9) and full seven-phase smoke
test against `codecartographer-pi@0.12.3`, not the local tarball.
- [x] Verify the GitHub Release targets the same commit as the tag.
- [x] Update the website to v0.12.2 only after npm is readable publicly, replace
- [x] Update the website to v0.12.3 only after npm is readable publicly, replace
stale cPanel instructions with the actual GitHub Pages workflow, and
verify the Pages build completed on the merged commit.
- [ ] Verify the live website in a fresh/private browser session and check its
install, GitHub, npm, video, and case-study links.

**Gate 1 passed on 2026-07-22:** v0.12.2 is installable from npm; the published package
**Gate 1 passed through 2026-07-23:** v0.12.3 is installable from npm; the published package
passes the MCP smoke test; GitHub `main`, GitHub Release, npm, and the website
agree on version and positioning; and no surface calls synthesis unreleased.

Expand All @@ -267,9 +269,9 @@ the API rather than assumed from a successful CLI exit.
comes after npm publication because npm supplies ownership verification.
- [x] Authenticate with the Gate 0 GitHub identity and an organization-owner
grant carrying `read:org`.
- [x] Publish the `server.json` matching the v0.12.2 tag.
- [x] Publish the `server.json` matching the v0.12.3 tag.
- [x] Query the registry API for the exact server name.
- [x] Confirm the result shows v0.12.2, the npm identifier, stdio transport,
- [x] Confirm the latest result shows v0.12.3, the npm identifier, stdio transport,
description, and repository URL.
- [x] Record API verification as the present coverage limit because no
registry-aware client was available for this release check.
Expand All @@ -278,8 +280,9 @@ the API rather than assumed from a successful CLI exit.
- [ ] Record CLI version, authentication mode, commands, output, and recovery
steps in the release issue without storing credentials or tokens.

**Gate 2 passed on 2026-07-22:** the registry API returns one unambiguous, installable
CodeCartographer entry whose metadata matches the published npm package.
**Gate 2 passed through 2026-07-23:** the Registry API marks one version as latest,
and that v0.12.3 record matches the published npm package. Older published
versions remain available as non-latest history.

### Follow-up automation

Expand All @@ -295,7 +298,7 @@ After Gate 2 has remained stable for at least one day:
## Workstream C — Produce the proof package

Store stable case-study indexes under `examples/` and launch-ready images under
`docs/assets/launch/v0.12.2/`. Full generated workspaces may be large; keep the
`docs/assets/launch/v0.12.3/`. Full generated workspaces may be large; keep the
useful artifacts in git and provide a reproducible generation recipe rather than
committing caches, dependency trees, session transcripts, or secrets.

Expand All @@ -313,7 +316,7 @@ Every case study must include:

### C1. CodeCartographer maps itself

- [ ] Run an analysis pipeline against the v0.12.2 tag in an isolated workspace.
- [ ] Run an analysis pipeline against the v0.12.3 tag in an isolated workspace.
- [ ] Publish architecture, contracts, defects, porting bundle, and
reimplementation-spec artifacts or clearly explain any omitted phase.
- [ ] Highlight three claims and trace each back to source evidence.
Expand Down Expand Up @@ -470,7 +473,7 @@ amount. Do not compress case-study verification to recover the calendar.

```text
Gate 0 decisions
-> v0.12.2 public release
-> v0.12.3 public release
-> npm + GitHub Release + website verification (Gate 1)
-> MCP Registry publication (Gate 2)
-> reproducible case-study version pins
Expand Down Expand Up @@ -525,7 +528,7 @@ Within 30 days:

This plan is complete when:

- v0.12.2 is the consistent public version across npm, GitHub, registry, and
- v0.12.3 is the consistent public version across npm, GitHub, registry, and
website;
- a clean user can start the MCP server from the published npm package;
- the official MCP Registry returns the correct server record;
Expand Down