Skip to content

docs: align homepage with the new README positioning - #16

Open
TheAmericanMaker wants to merge 1 commit into
mainfrom
docs/align-site-with-readme-positioning
Open

docs: align homepage with the new README positioning#16
TheAmericanMaker wants to merge 1 commit into
mainfrom
docs/align-site-with-readme-positioning

Conversation

@TheAmericanMaker

Copy link
Copy Markdown
Member

Follow-up to roadmap item 3. The site is not a placeholder — it's a full site — so this aligns it with the positioning merged in CodeCartographer#77 rather than building something new.

Why

The README hero was rewritten to lead with the problem instead of the category, and to name the agents it works with. The site still led with Evidence-backed software cartography, so the two surfaces pitched the product differently to the same visitor.

Before After
Eyebrow Evidence-backed software cartography · v0.12.11 Works with Pi, Claude Code, Cursor, and Codex · v0.12.11
Headline Understand existing software. Plan what comes next. Understand an unfamiliar codebase. Get a spec you can rebuild from.

Changes

  • Hero copy matches the merged README wording.
  • New dashboard section with a real render from the demo workspace — the dashboard is the most distinctive thing about the product and no prose conveys it. The dark screenshot sits fine against the light theme because the existing hero preview panel is already dark.
  • MCP card links to the new copy-paste quickstart.

Bug found along the way

The Pi card advertised three commands and had quietly dropped /codecarto-vision and /codecarto-switch-pipeline. The extension registers 15.

There was no test guarding this — docs.html had one for MCP tool names, but nothing checked Pi commands, which is how the drift got in. Added one that fails if the site cites a /codecarto-* command the extension doesn't register, or states the wrong count. Verified it fails on an invented command rather than passing vacuously.

The version-label test previously pinned the eyebrow to the literal string Evidence-backed software cartography · vX.Y.Z. It now just requires the current version to appear there, so marketing copy can change without a test edit.

Verification

  • 8/8 site tests pass (7 existing + 1 new)
  • Rendered locally in Chromium at 1280px and inspected the hero and the new dashboard section

One judgment call for you

The dashboard screenshot reads "Attention Required" in large text, because the active contracts phase hasn't written its artifact yet. That's the honest mid-run state and any mid-run screenshot shows it. If you'd rather the homepage show a completed 7/7 run, it's a one-image swap — same question as the README hero.

Repo state note

The local checkout was behind 8 / ahead 1, not in sync. The local commit was a superseded duplicate of upstream #13 whose only unique content was older version labels, so I reset to origin/main; it's tagged local-stale-c9cbb4f locally if you want it. Its one good part — the longer command list — is restored here deliberately.

The README hero was rewritten in CodeCartographer#77 to lead with the
problem instead of the category ("cartography"), and to name the agents it
works with. The site still led with the old line, so the two surfaces
pitched the product differently.

- Hero eyebrow: "Evidence-backed software cartography" -> the agents it
  works with, which is what a visitor is actually checking for.
- Headline and subhead now match the merged README wording.
- New dashboard section with a real render from the demo workspace. The
  dashboard is the most distinctive thing about the product and no prose
  conveys it.
- MCP card links to the new copy-paste quickstart.

Also fixes a factual regression: the Pi card advertised three commands and
had quietly dropped /codecarto-vision and /codecarto-switch-pipeline. The
extension registers 15. Added an upstream-consistency test that fails if
the site cites a /codecarto-* command the extension does not register, or
states the wrong command count — the same guard the MCP tool list already
had. Verified it fails on an invented command.

The version-label test no longer pins the eyebrow to the old marketing
line; it still requires the current version to appear there.

8/8 site tests pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant