Go public: a README that reads like a project, plus CONTRIBUTING and SECURITY - #48
Merged
Conversation
…SECURITY The README's first screen was a title, a one-line description and a status blockquote that was flatly untrue — M1 and M2 are both done. It now opens with what the thing is, a three-command quickstart, and an honest status line, so a visitor with thirty seconds gets the shape of it before any prose. Seven claims were wrong or missing, found by running the commands rather than reading them: "One card per session" predates ADR-0015 (a day of a session is a card); "Four things underneath it are mechanical" sat above six commands; Codex capture, `crate day`, `crate lint` and per-card token usage were absent entirely; and "Three layers:" headed a four-row table, CONVENTIONS.md being Layer 3's second owner rather than a fourth layer. Adds a "Why not just…" section, because chat history, RAG and Obsidian-alone are the comparisons a reader arrives with and the README never answered them; and a commands table, which is where the invisible commands stop being invisible. CONTRIBUTING.md and SECURITY.md say what is actually true: no PRs during the deliverable sequence, issues welcome, and a private route for a security report. SECURITY.md's advisory link needs private vulnerability reporting enabled, so that command joins topics in the flip runbook. Refs #27 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The snippet's job is to show the nesting — hooks -> Stop -> array -> object -> hooks -> array — and the one-line form collapsed exactly that. It now matches the shape `crate install-hook` writes, so the two can be compared side by side. Refs #27 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
samplerdisc went public with three badges, tagged releases, a changelog, a code of conduct, issue and PR templates, and a README that says plainly what does not work yet. crate-wiki had the first half of that and not the second. Adds CHANGELOG.md with a 0.1.0 entry covering M1 and M2, CODE_OF_CONDUCT.md (Contributor Covenant 2.1, same text as samplerdisc), an issue form whose first instruction is not to paste transcripts, and a PR template carrying the verify checklist from CLAUDE.md. README gains a licence badge, an explicit install heading with the pip alternative, and two sections the samplerdisc README earns its credibility with: "What doesn't work yet" — no source ingesters, no MCP server, Codex swept by hand, the open forked-session double-count (#41), capture silent by contract, one person's scale — and "If something doesn't work", which is where the capture log stops being buried in a bullet. The status line now claims the dogfooding rather than hedging it. The runbook gains a fuller repo description, three more topics, and the commands to cut v0.1.0 once main carries this. Refs #27 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs #27 — the README pass and the repo-furniture half of the go-public checklist. Not
Closes: #27 keeps its flip-time items (pushmain, branch protection, topics, the flip itself).Why
The first thing a visitor read was false. Line 5 said "Milestone 1 is in progress"; M1 and M2 are both complete and only M3 Reach is open. The rest of the first screen was a title, a one-line description and that blockquote — no sense of what running this looks like.
What changed
The first screen. Title, one-liner, two badges (CI, Python 3.11+), a hook paragraph, a three-command quickstart, an honest status line, and a sentence on what stays local. The problem statement's strongest sentence moves up into the hook;
## The problemstays below the fold in full.Seven corrections, found by running the commands rather than reading them:
CONVENTIONS.mdnamed as Layer 3's second owner/ingest/daily,/askand/lintcrate capture codexand/fetch-codexdocumentedcrate day,crate lint, token usage invisibleNew sections. "Why not just…" answers chat history, RAG and Obsidian-alone — the comparisons a reader arrives with. "The commands" lists the CLI once, with
crate <command> --helpnamed as the reference rather than duplicating it here.New files.
CONTRIBUTING.md(no PRs during the deliverable sequence, issues welcome, synthetic fixtures only) andSECURITY.md(private advisory route, scope framed around data staying local). Both say what is true; a file describing a process nobody runs would be worse than none.Runbook.
SECURITY.md's advisory link 404s until private vulnerability reporting is on, so thatghcommand joins the ten proposed topics in the flip section ofdocs/going-public.md. Documented for a human to run, not run here.Deliberately not added: banner image, FAQ heading,
CODE_OF_CONDUCT.md,CHANGELOG.md,CITATION.cff, issue and PR templates. No ADR — nothing here rejected a real alternative that the existing records don't already cover.Verification
ruff check,ruff format --check,pytest -q(353 passed), and gitleaks over the change — all clean. No source changes.Every command the README shows was run against a fresh vault in a scratchpad:
init,install-hook(withHOMEredirected so the real~/.claude/settings.jsonwas untouched),capture claudeon a synthetic transcript,pending,day,new,extend,fmt,index,log,upgrade --dry-run,capture codex.crate lintcame out clean on the resulting vault, and reporteddead-linkwhen one was introduced. The only line not executed end to end isuv tool install git+https://…, which needs the repo public; the install path was verified withuv tool install ..🤖 Generated with Claude Code