Skip to content

docs(readme): add generated project banner and entry links - #258

Open
HomenShum wants to merge 3 commits into
mainfrom
claude/readme-banner
Open

HomenShum wants to merge 3 commits into
mainfrom
claude/readme-banner

Conversation

@HomenShum

@HomenShum HomenShum commented Oct 7, 2026 •

Copy link
Copy Markdown
Owner

What changes

The plain # Title at the top of the README becomes a generated banner, followed by a row of links to entry points that exist in this repository. Nothing else in the README changes. If the line under the title only repeated the banner's tagline word for word, it is removed.

Added What it is
docs/brand/banner-{light,dark}.svg 1280×400 banner (~30 KB). Text is outlined, so every reader sees the same type.
docs/brand/compact-{light,dark}.svg Phone version, served under 600 px wide, where the wide banner's labels would shrink to ~4 px.
README block between brand:start and brand:end A <picture> that picks light or dark and wide or phone, plus the link row.

Why

The README is the page people land on. It now shows what the project is and its workflow in one consistent visual system across all 19 portfolio repositories. It links to the code walkthrough, the handoff and the live demo where those exist. It also links to homenshum.github.io, which gives each project its own indexable page.

Evidence

  • Rendering on github.com: checked on a pushed branch. GitHub keeps the <picture> media queries and rewrites the relative srcset paths. Desktop light and dark load the wide banners (838 px). Phone light and dark load the phone banners (324 px). All four images loaded.
  • Motion contract (tools/brand/motion-check.mjs, real Chromium, <img> embed):
    • The first frame is already complete. Nothing animates in, so a frozen or offscreen render still shows the whole banner.
    • Mid-run, a single accent signal runs the steps in order, then settles on the outcome.
    • With prefers-reduced-motion, every frame is pixel-identical to the final one.
  • The README injector (tools/brand/readme.test.mjs) passes 8 scenarios:
    • # lines inside code fences are left alone.
    • A duplicate subtitle is removed; a different subtitle is kept.
    • Re-running refreshes the block instead of adding a second one.
    • A README with no H1 is an error, not a silent insert.
    • CRLF line endings are preserved.

To change it

Edit this repository's entry in tools/brand/repos.json, rebuild with npm run brand, then run node tools/brand/readme.mjs <this checkout> <Repo>. Edit there, not here: the block is regenerated.

Current source and verification

The project heading and its permalink are restored below the existing generated banner. Every prior README passage and all four SVG assets are preserved; this follow-up commit changes only the README heading.

Updated-revision PR and push CI remain red at the production dependency audit: 12 findings, including one high-severity undici finding (PR CI, push CI). Subsequent production-gate checks did not run. Earlier CI failed at the production dependency audit. The banner's broad collaboration wording still requires review; this heading repair does not certify concurrent editing.

Pinned repaired source: 1657a2d89d763d755c99213ea4f1e230635638ce (heading repair, reviewed earlier; it covers that document patch only). Head 4e5c41a000eb047e298d18444b084b14394fb91a adds one commit that refreshes the four docs/brand SVGs to the AA-contrast version from HomenShum.github.io 234bf22; README.md is unchanged by it. verify is still red on this head at npm audit --omit=dev --audit-level=moderate (undici, fixed by #256); see the status comment on this PR.

🤖 Generated with Claude Code

@vercel

vercel Bot commented Oct 7, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
noderoom Ready Ready Preview Oct 10, 2026 8:38am UTC

Request Review

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown

Scaffold Handoff — For Your Coding Agent

Your coding agent (Codex, Claude Code, etc.) should apply the accepted
scaffold proposals below. Do NOT touch any immutable files.

Immutability Check

Mode: advisory

✅ No immutable files were modified in this branch.

Changed Files

  • README.md
  • docs/brand/banner-dark.svg
  • docs/brand/banner-light.svg
  • docs/brand/compact-dark.svg
  • docs/brand/compact-light.svg
  • docs/eval/OFFICIAL_BENCHMARK_READINESS.md
  • docs/eval/OFFICIAL_BENCHMARK_TASK_COVERAGE.md
  • docs/eval/OPENROUTER_CONVEX_BENCHMARK.md
  • docs/eval/agent-improvement-loop.md
  • docs/eval/agent-improvement-loop.svg
  • docs/eval/agent-improvement-loop/20261010T083700Z.json
  • docs/eval/agent-improvement-loop/latest.json
  • docs/eval/agent-workspace-sandbox-smoke.json
  • docs/eval/algorithm-artifact-smoke.json
  • docs/eval/bankertoolbench-official-contract.json
  • docs/eval/docker-sandbox-probe.json
  • docs/eval/eval-runs.jsonl
  • docs/eval/halo-convex-context-telemetry.json
  • docs/eval/halo-self-improvement-smoke.json
  • docs/eval/halo-variant-selection.json
  • docs/eval/official-benchmark-readiness.json
  • docs/eval/official-benchmark-task-coverage.json
  • docs/eval/openrouter-convex-benchmark.json
  • docs/eval/professional-catalog-proofs.json
  • docs/eval/professional-proof-ledger.json
  • docs/eval/spreadsheetbench-chart-visual-probe.json
  • docs/eval/traces/credit/20261010T083709272Z-e027bf2f_dirty.0a630729f3850585/cascade-healthy.json
  • docs/eval/traces/credit/20261010T083709272Z-e027bf2f_dirty.0a630729f3850585/delta-incomplete.json
  • docs/eval/traces/credit/20261010T083709272Z-e027bf2f_dirty.0a630729f3850585/mapping-correct.json
  • docs/eval/traces/credit/20261010T083709272Z-e027bf2f_dirty.0a630729f3850585/mapping-misbind.json
  • docs/eval/traces/credit/20261010T083709272Z-e027bf2f_dirty.0a630729f3850585/summit-stressed.json
  • docs/eval/traces/ladder/20261010T083708811Z-e027bf2f_dirty.2cec5516f5a124f3/ladder_L1_read_scripted.json
  • docs/eval/traces/ladder/20261010T083708811Z-e027bf2f_dirty.2cec5516f5a124f3/ladder_L2_edit_scripted.json
  • docs/eval/traces/ladder/20261010T083708811Z-e027bf2f_dirty.2cec5516f5a124f3/ladder_L3_conflict_scripted.json
  • docs/eval/traces/ladder/20261010T083708811Z-e027bf2f_dirty.2cec5516f5a124f3/ladder_L4_blocked_scripted.json
  • docs/eval/traces/ladder/20261010T083708811Z-e027bf2f_dirty.2cec5516f5a124f3/ladder_L5_large_range_scripted.json
  • docs/eval/traces/ladder/20261010T083708811Z-e027bf2f_dirty.2cec5516f5a124f3/ladder_L6_long_horizon_scripted.json
  • docs/eval/traces/ladder/20261010T083708811Z-e027bf2f_dirty.2cec5516f5a124f3/ladder_L7_resume_scripted.json

Needs Adversarial Review — Do NOT Apply Yet

These proposals passed the reject check but have not been approved by
an adversarial reviewer. A human or frozen LLM judge must approve them first.

  • scaf-001 (AGENTS.md): Add explicit instruction for step spreadsheetbench-runner-fixture: Step spreadsheetbench-runner-fixture failed — scaffold may need explicit instruction or evidence assertion.
  • scaf-002 (AGENTS.md): Add explicit instruction for step convex-boundaries: Step convex-boundaries failed — scaffold may need explicit instruction or evidence assertion.

Safety Boundary

Agent may improve the scaffold.
Agent may NOT weaken the proof gate.

Immutable files (never modify):

  • scripts/proofloop.mjs
  • scripts/agent-improvement-loop.ts
  • tests/harnessChangeEval.test.ts
  • .github/workflows/
  • src/eval/evalTrustPolicy.ts
  • src/eval/architectureBudget.ts
  • evals/evalStore.ts

Scaffold files (safe to modify):

  • AGENTS.md
  • CLAUDE.md
  • proofloop/scenarios/*.yaml
  • proofloop/rubrics/*.yaml
  • proofloop/subagents/*.md
  • proofloop/adapters/*.js
  • .proofloop/memory.jsonl
  • src/nodeagent/models/prompts/systemPrompt.ts

Replaces the plain H1 with a light/dark, wide/phone banner generated by
HomenShum.github.io (tools/brand) and a row of links to files that exist.
The rest of the README is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The animated step label now peaks at #9c4f37 instead of #D97757, so it keeps
4.5:1 on the light surface (homenshum.github.io 787f1bc). README.md is
unchanged; only the four docs/brand SVGs differ.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@HomenShum

Copy link
Copy Markdown
Owner Author

Status on head 4e5c41a (adds one commit on top of 1657a2d: the four docs/brand SVGs now match HomenShum.github.io brand/NodeRoom/*.svg at 234bf22, with the AA-contrast animated label colour; README.md is unchanged and the # NodeRoom heading is still directly under <!-- brand:end -->).

verify fails on this head at the first command of the "Production gate" step, npm audit --omit=dev --audit-level=moderate: undici 8.0.0 - 8.10.1 (1 high), 12 vulnerabilities (11 low, 1 high), exit code 1. Jobs: PR run, push run. The same failure was on the previous head (job 112975913299, job 112975894764). None of the later gate commands, including proofs:staleness, ran.

The fix is Codex #256 (undici ^8.11.2). This PR is not the place to carry it (#259, a duplicate, is closed). After #256 merges, this PR needs a rebase onto main.

Even then, npm run proofs:staleness will still need a signed-in production proof run on https://noderoom.live by Homen, because docs/eval/noderoom-fresh-user-vertical-proof.json is more than 30 days old. This PR only touches README.md and four SVGs and cannot clear that. It stays unmerged until verify is green.

This branch was successfully deployed

1 active deployment
Preview — 4e5c41a0 Deployed Oct 10, 2026 by vercel[bot]
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