docs(readme): from-scratch rewrite for v3.0 - #731
Merged
Conversation
The pre-v3 README accumulated layers across v1/v2 and several sections overlapped: 'What makes aelfrice different' (8 bullets) re-stated what 'What it does' + 'What it remembers' + 'What you get for free' then covered in more detail. The v3.0 reasoning surfaces (/aelf:wonder and /aelf:reason) were buried as a subsection of the day-to-day CLI list. Rewrite per the three structural decisions from operator alignment: 1. Passive-memory headline stays primary; wonder/reason are a peer 'Reasoning surfaces (v3.0)' section, not a sub-bullet under CLI. 2. Lin's pillars table preserved (still the strongest non-marketing positioning piece) but every aelfrice column reframed for v3: - Provenance: scope field for federation (#688), eight origins incl. speculative for /aelf:wonder phantoms. - Write gates: phantom-promotion Surface A + Surface B (#550) with explicit audit-row tags (promotion:user_validated, promotion: phantom_lock_match). - Conflict handling: typed VERDICT + IMPASSES from /aelf:reason (#645) and ConsequencePath fork-on-CONTRADICTS (#658). - Reversibility: read-only federation (#650/#655) with ForeignBeliefError on foreign-id mutations. 3. Memory-model table absorbs 'What it remembers' + the Beta-Bernoulli intro that was previously a standalone bullet; adds aelf promote and /aelf:wonder rows so the v3 verbs are discoverable. Cuts: 'What makes aelfrice different' 8-bullet manifesto (info distributed across How-it-works + Memory-model + What-you-get-for-free, no information lost); the standalone 'Session-start enrichment vs per- turn retrieval' subsection (folded into How-it-works as a single sentence with pointer to ARCHITECTURE); the decorative 'aelf stats' output block. Lead sentence drops the 'in Claude Code' phrase -- the README still works for any UserPromptSubmit-capable agent host, and dropping the specific harness name lets the rewrite pass the pre-push discretion grep cleanly (-40 lines net while adding v3 content).
![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 (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughREADME.md is rewritten to present aelfrice v3.0 as a background memory substrate injected via the Changesaelfrice v3.0 Documentation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 151: The README's "Local-only. ... No telemetry, no network calls"
sentence is too absolute; update the phrasing so it scopes network behavior to
the aelfrice core/process (e.g., "aelfrice itself makes no network calls") and
explicitly note that host-dispatched subagent LLM calls may still occur
elsewhere in the flow; modify the sentence containing "Local-only. SQLite ... No
telemetry, no network calls, no accounts." and keep references to
knowledge_deps.json and PRIVACY.md intact while clarifying the distinction with
host-dispatched subagents.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
Line 151 said 'No telemetry, no network calls' absolutely, but line ~90 in the same file documents subagent LLM dispatch as part of /aelf:wonder and /aelf:reason flows -- which do touch the network (under the host agent's credentials, not aelfrice's). CodeRabbit flagged the internal contradiction. Reword to 'aelfrice itself makes no network calls' with an explicit parenthetical naming the subagent-dispatch exception. The retrieval- path-stays-local invariant is preserved verbatim because that's the actual contract.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 47: The README contains a broken anchor link to
docs/ARCHITECTURE.md#claude-code-hook; locate the reference in README.md and
either change the anchor to an existing section (for example
docs/ARCHITECTURE.md#retrieval) or add the missing section/anchor
"claude-code-hook" (Session-start enrichment) in docs/ARCHITECTURE.md so the
link resolves; update only the README link or the ARCHITECTURE file accordingly
to keep documentation consistent.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
…ntinel path CodeRabbit's link-check flagged the [ARCHITECTURE § Session-start enrichment](docs/ARCHITECTURE.md#claude-code-hook) cross-link. The anchor #claude-code-hook is technically valid (GitHub auto-slugs the '## Claude Code hook' heading) but the target section doesn't deep- dive into session-start enrichment specifics -- only a one-line mention in the v1.2+ hooks table. Rather than add a new Session-start enrichment subsection to ARCHITECTURE.md (out of scope for this PR), drop the link and inline the one operational detail readers would have followed it for: the session_first_prompt.json sentinel path. That preserves the information the original pre-rewrite README carried in a longer subsection.
robotrocketscience
added
the
ready-to-merge
github-actions
Bot
removed
the
ready-to-merge
|
merge-train: merged cbfe8be → |
7 tasks
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
Per-section restructure to match the v3.0 surface. Net change: +58 / -98 lines. Three structural moves keyed to operator alignment earlier today:
scopecolumn for federation (feat(federation): scope field on beliefs (#650 sub-task) #688); write gates document the phantom-promotion Surface A + Surface B ([v2.1] C4: phantom promotion trigger (#542 sub-task) #550); conflict handling cites the typedVERDICT+IMPASSESfrom/aelf:reason(feat(wonder+reason): full parity with agentmemory + harmonious merge with aelfrice extensions #645) andConsequencePathfork-on-CONTRADICTS(feat(reason): R2 — compound confidence decay + CONTRADICTS fork (#645 sub-task) #658); reversibility carries the read-only federationForeignBeliefErrorboundary (Umbrella: v3 cross-project federation — CRDT primitives + transport #650 / feat(federation): read-only mechanics — knowledge_deps.json + SQLite ATTACH + foreign-ID rejection (#650 sub-task) #655).aelf promote(with--to-scopemention) and/aelf:wonder.What's gone
aelf statsoutput block — not load-bearing.What's preserved verbatim
Test plan
+line contains "Claude Code", "Sonnet", "Opus", "Haiku", or any internal codename.textorbash, no MD040 candidates.Summary by CodeRabbit