docs: add GUIDE.md (extensive walkthrough + internals)#11
Open
srnnkls wants to merge 6 commits into
Open
Conversation
srnnkls
force-pushed
the
docs/guide
branch
3 times, most recently
from
June 11, 2026 17:03
8728d22 to
2794914
Compare
srnnkls
force-pushed
the
docs/guide
branch
4 times, most recently
from
June 15, 2026 09:49
e1d418c to
b5d2419
Compare
srnnkls
force-pushed
the
docs/guide
branch
2 times, most recently
from
June 24, 2026 14:16
db667d4 to
29491ca
Compare
Stacked on the selection-model-redesign branch (PR #44). Adds GUIDE.md, the long-form companion to the README, written to the source-offer / target-take model: source owns the offer (`root` + gitignore `include`/`exclude`), binding owns the `take` (literal / glob / `{ src = dest }` rename), artifacts are path-identified leaves, and a `collapse` opt folds a wholly-taken directory into one artifact. Adds use-case scrut walkthroughs that drive the shipped binary against real upstreams and double as runnable, CI-verified usage docs: showcase, drift, versions, release-assets, mapped (take renames), hooks, templates, and transitive. These sit alongside the branch's hermetic suites (selection, query, manage, lifecycle); the README testing section indexes both.
…t prose
Sweep flagged by a review pass. Replaces editorializing and overclaims with
plain, mechanism-grounded statements, e.g.:
- "precise enough to prove nothing drifted" -> "detect whether anything drifted"
- "stronger story than curl|tar: nothing touches your disk" -> "not extracted
until the digest check passes"
- "the order is the security property" -> "the order matters: digest before extraction"
- "a malicious archive cannot escape" -> "a crafted archive path cannot escape the
extraction root"
- drops scene-setting ("you at midnight", "the box under the desk", "Alice changes
jobs"), strained metaphors ("annotates the divorce"), and anthropomorphisms
("release tarballs love to 302", "the registry says so instead of pretending").
Prose-only; all 12 scrut suites still pass against the new-model binary.
Replace invented nvim/helix/vscode/editor/modules examples with the actual ~/dotfiles tree: srnnkls/dotfiles rooted at .config (zellij, ripgrep, codex, anax, mise), .shared/AGENTS.md fanned out to CLAUDE.md/codex.md, ~/projects/loqui for link mode, mise GOBIN for templating, mise hooks. Paths verified against the layout kernel and scrut tests.
…dual risk Track the 16ad1a4..6281e9d range across guide + scrut: - trust inspection (THI): document `trust <source> --show <path>` and the first-trust composed-file listing in README + GUIDE; extend transitive.md with --show (file/dir/absent/no-source) and the composed-surface assertion. - drift gate (DGI): GUIDE Verification now describes the size+mtime fast path escalating to recorded blake3, the Revalidated reclassification, and the persisted stat refresh; drift.md gains a 'touch is not a change' case. - residual risk (TDEP-DOCS-001): state the honest v1 hook-trust limits (no sandbox, full env+privileges, whole-commit re-prompt) in README + GUIDE. transitive.md's `phora verify` assertion is reconciled with the post-16ad1a4 verify hook-gate so the suite passes against the feature-complete binary.
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.
A long-form companion to the README, following the ripgrep README/GUIDE split: the README stays terse and flag-level; this is the depth.
What's in it
phora.toml, whatphora syncdoes step by step, thenlist/verify/update.~/.phora,MirrorKey/ProjectIdkeying, syntheticrefs/heads/phora),blake3digest,state.lock+ deploy journal + recovery sweep (no fictional concurrency; sync is sequential).Every technical claim is grounded in the implementation. The README links here for depth (that link lands with #10).
Marked as its own PR per request; can be split into README-guide + internals-guide later if it grows.