docs(readme): consumer-readability pass (page-cro v2) - #735
Merged
Conversation
The .agents/ directory holds product marketing context (ICP, positioning, competitive analysis, customer language) consumed by the coreyhaines31/marketingskills plugin. Content is positioning-internal, not public README material — kept local-only by gitignore.
Replaces 'Local SQLite. Fully auditable. No GPU, no network.' with 'No cloud. No account. No telemetry.' Three-fragment rhythm preserved. Reason: page-cro v2 B1 — the third hero line jargon-tripped non-technical readers right after two consumer-readable lines. SQLite / auditable / GPU claims survive in 'How it works' and 'What you get for free' below.
Page-cro v2 NF1: the from-scratch rewrite (cd6dd34) replaced the amnesia-painkiller opener ('aelfrice runs in the background and stops the amnesia and context drift') with 'aelfrice is a memory substrate that runs in the background of your coding agent' — engineer-voice that loses the value-prop hook for the tired-AI-user persona. Restored the opener as 'aelfrice runs in the background and stops the amnesia.' Kept the rewrite's two-clause mechanism explanation that follows (no CLAUDE.md chain, no cross-references for the agent to skip, matched beliefs in the prompt). Dropped 'and context drift' as a minor trim — the amnesia frame carries the painkiller alone.
Page-cro v2 NF2: the from-scratch rewrite (cd6dd34) deleted the outcome-led 'What makes aelfrice different' section without replacing its consumer-readable value-prop framing. Result: the new README is well-served for the skeptical-engineer persona (How it works / Memory model / Lin's pillars carry the receipts) but the tired-AI-user persona has nothing to land on between Install and the technical detail. This commit re-introduces four plain-language bullets between Install and How it works: - Stops the AI forgetting your rules. (outcome — the painkiller; aelf lock as the concrete action.) - The AI can't skip it. (mechanism in plain words.) - Stays on your computer. (privacy + reversibility merged.) - Set up once. Forget it's there. (friction-low framing.) No technical content moved; the existing How-it-works / Memory model / Lin's-pillars / What-you-get-for-free sections that follow are all preserved as the proof tier. The new section is the claim; what follows is the receipt. Voice locked to .agents/product-marketing-context.md § 'Words to use above the fold' — 'remember,' 'rule,' 'stays on your computer,' 'the AI can't skip it,' 'set up once.' No 'deterministic,' 'provenance,' 'audit trail' jargon up top.
Page-cro v2 B5: the rewrite jumps straight from the heading into 'four retrieval lanes / UserPromptSubmit hook / prepends... aelfrice- memory block' (line 38), then the lane diagram puts FTS5 / BM25 / Plate-FFT bind/probe / NDCG@k receipts on top of that. The skeptical- engineer persona is well-served; the non-technical reader bounces. Added one short sentence before the existing technical paragraph: 'In plain English: four searches run in parallel over your stored rules, the best matches get prepended to your prompt, and the model reads the lot as one message. Below is the wiring for readers who want the receipts.' Existing technical detail unchanged. The plain-English lead-in lets the non-technical reader skim to the next section with the gist intact; the engineer keeps reading for the receipts.
Page-cro v2 B7: the 4-row Lin's-pillars table cells got denser after the rewrite, with v3.0 additions (scope #688, phantom-promotion #550, verdict/impasse #645/#658, federation #650/#655) layered on top of the older field-level detail. Mobile rendering remains broken either way; this commit reduces cell density so desktop reading is faster without losing the v3.0 receipts. Per locked decision, kept the v3.0 issue refs and their semantics (#688 scope, #550 phantom promotion surfaces, #645/#658 verdict/impasse classifiers, #650/#655 read-only federation). Trimmed older field- level detail that doesn't carry load: - Row 1 (Provenance): dropped 'with source kind, source path, and session id', 'content_hash binds each row to its content', 'belief_versions / edge_versions sidecar tables carry per-scope version vectors' (the version-vector point is restated in row 3). - Row 2 (Write gates): dropped 'Two-tier lock state: lock_level in {none, user} with a locked_at timestamp and a demotion_pressure counter that blocks silent removal' (implementation detail). Kept the v3.0 phantom-promotion (#550) surface description verbatim. - Row 3 (Conflict handling): dropped 'in src/aelfrice/models.py' (file pointer redundant when it appears in row 1). 'instead of guessing' qualifier dropped. - Row 4 (Reversibility): collapsed the per-verb audit-row enumeration (aelf delete... aelf unlock... aelf promote --to-scope... aelf feedback...) into one sentence. Kept the v3.0 read-only federation (#650 / #655) description. No v3.0 receipt removed. ~25-35% cell-length reduction; mobile rendering improves (less paragraph-cell wrap).
Page-cro v2 cleanups bundled into one commit (each is one line): NF4 - 'AST' -> 'code structure' in the aelf onboard install comment. Same scope of what's scanned; readers who want the precise AST detail can consult COMMANDS.md. 'AST' as a bare acronym in the hero install block is jargon for non-technical readers. Session-path leak - dropped '<git-common-dir>/aelfrice/session_first_ prompt.json' from the How-it-works closing sentence. The implementation sentinel path belongs in INSTALL.md (it's already there); 'One extra block per new session, not per prompt' carries the same user-facing meaning. NF3 - dropped 'Initial prior (9.0, 0.5)' parenthetical from the 'What it remembers' table row. The (9.0, 0.5) prior is a real implementation detail but reads as jargon in a marketing-shaped table. 'Permanent rule. Returned on every retrieval.' is the user-facing claim; the prior detail belongs in PHILOSOPHY.md or the lock-API doc.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Sorry @robotrocketscience, you have reached your weekly rate limit of 500000 diff characters.
Please try again later or upgrade to continue using Sourcery
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThe PR updates branding, installation documentation, and memory system descriptions in ChangesDocumentation and Configuration Updates
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related PRs
Suggested labels
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
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.
Summary
Targeted edits to the post-rewrite README (
cd6dd34) to close the consumer-readability gap that the from-scratch rewrite left open. Diagnosed via thepage-croskill against the new structure (.agents/PAGE-CRO-v2.md, local-only) on top of the positioning doc (.agents/product-marketing-context.md, local-only — both gitignored).The rewrite optimized for the skeptical-engineer persona (How it works, Memory model, Lin's pillars all carry receipts). This PR re-introduces the value-prop framing for the tired-AI-user persona without touching any of the technical proof.
What changed (7 atomic commits)
4cbb054.gitignore— add.agents/9db81b5_Local SQLite. Fully auditable. No GPU, no network._→_No cloud. No account. No telemetry._Same 3-fragment rhythm; SQLite / auditable / GPU still surface in How-it-works and What-you-get-for-free.b4f8efa3dd7bb783d4ab6fb50f66lock_level,locked_at,demotion_pressure,content_hash,belief_versions/edge_versionssidecar). ~25-35% cell-length reduction; no v3.0 receipt lost.7dd71f3AST→code structurein install comment; (b) dropped<git-common-dir>/aelfrice/session_first_prompt.jsonpath leak from How-it-works (belongs in INSTALL.md, already there); (c) droppedInitial prior (9.0, 0.5)parenthetical from the marketing-table row.Net diff
What this PR does NOT touch (intentionally)
Your AI stops forgetting / Set up once. Stays out of the way.tagline — kept verbatim (locked).aelf lockexample inside the install bash block.uv tool install aelfriceis already on main via Collapse install/upgrade surface to uv-only #730.Foundation artifacts (local-only, not in this PR)
Two positioning docs live in
.agents/(gitignored by this PR's commit 1):.agents/product-marketing-context.md— ICP, competitive landscape, voice rules, words-to-use / words-to-avoid lists. Built via theproduct-marketing-contextskill..agents/PAGE-CRO-v2.md— the diagnosis report this PR addresses, re-run against the new post-rewrite README structure (supersedes a stale v1 against the pre-rewrite README).These stay local — they're positioning-internal, not public README material.
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Chores