Skip to content

docs: README — sharper why + layered examples#10

Merged
VGonPa merged 1 commit into
developfrom
readme-why-layers
May 19, 2026
Merged

docs: README — sharper why + layered examples#10
VGonPa merged 1 commit into
developfrom
readme-why-layers

Conversation

@VGonPa
Copy link
Copy Markdown
Owner

@VGonPa VGonPa commented May 19, 2026

Follow-up to the README rewrite. Two improvements requested:

  • A real "Why XBrain" section — the second-brain gap (a PKM captures what you produce, nothing of what you consume), why a bookmark pile is signal worth recovering, and who it is for.
  • The three layers explained with concrete examples — each layer (Items / Topics / Index) now shows an actual rendered note from a generated vault, so a reader sees exactly what the tool produces. The Topics section makes the key point explicit: a topic page is an essay, not a list of links.

Docs-only. Examples are real output (Spanish, as the rubrics specify — noted in the README).

🤖 Generated with Claude Code

@VGonPa VGonPa merged commit f831521 into develop May 19, 2026
1 check passed
@VGonPa VGonPa deleted the readme-why-layers branch May 19, 2026 16:55
@VGonPa VGonPa mentioned this pull request May 19, 2026
Merged
VGonPa added a commit that referenced this pull request May 21, 2026
@VGonPa @claude
[#17] address 6-reviewer panel: critical PRD guarantees + safety hard…
e89c5c5 
…ening

Addresses every HIGH/CRITICAL finding from the review pipeline on PR #22
(code-reviewer, silent-failure-hunter, pr-test-analyzer, python-code-reviewer,
code-simplifier, spec-compliance):

snapshot.py:
- snapshot_create returns (Path, SnapshotManifest) — callers (incl. _auto_snapshot)
  now print the item count from the manifest just written, matching PRD §5
  observability ("Snapshot created: <path> (N items)").
- New `dir_label` parameter separates directory naming from manifest.command:
  manifest now records "vocab-regenerate" (the op name) while the directory
  carries the `pre-` prefix. Fixes the dual-purpose smell flagged by code-reviewer.
- snapshot_pre removed — inlined in _auto_snapshot (code-simplifier).
- Timestamp gains millisecond precision (`%Y-%m-%dT%H-%M-%S-NNNZ`). Eliminates
  the same-second collision bug flagged by pr-test-analyzer #9 and
  python-code-reviewer #2. As a side effect, the suite no longer needs
  `time.sleep(1.1)` between snapshots — total test runtime dropped from 7s to <1s.
- snapshot_restore now uses `shutil.copy2` symmetrically with snapshot_create
  instead of the text round-trip via `_atomic_write`. Binary-safe, metadata-
  preserving, and no longer asymmetric (code-reviewer/python-code-reviewer
  both flagged this as the must-fix-before-merge issue).
- snapshot_restore returns a list of (artifact, action) tuples — RESTORE_COPIED,
  RESTORE_DELETED, RESTORE_SKIPPED. The CLI prints every action, so a deletion
  from a "missing in snapshot" artifact is never silent (silent-failure-hunter
  #1 HIGH).
- snapshot_list now returns rows with `manifest=None` for corrupt directories
  instead of silently dropping them; the CLI marks those as CORRUPT on stderr
  (silent-failure-hunter #2 HIGH).
- _count_* helpers now propagate exceptions instead of swallowing them — a
  corrupt items.json aborts the snapshot, not records a lying count=0
  (silent-failure-hunter #3, code-reviewer #3). Inlined the trivial
  _count_items/_count_topics wrappers (code-simplifier #1).
- All imports (json, yaml, importlib.metadata) at the module top (code-reviewer #3).
- _count_items/_count_topics removed (one-line wrappers, code-simplifier #1).

cli.py:
- _OPERATOR_ERRORS now includes OSError (covers PermissionError, FileExistsError,
  IsADirectoryError) so snapshot I/O failures surface as clean exit-1 instead
  of raw tracebacks (silent-failure-hunter #4).
- _auto_snapshot now reads the count from the manifest and emits the spec-
  mandated English message: `Snapshot created: <dir> (N items)` (pr-test-analyzer
  #10, python-code-reviewer #3).
- snapshot_restore_cmd echoes every per-artifact action.
- snapshot_list_cmd handles `manifest=None` rows as CORRUPT (to stderr).
- snapshot_create_cmd uses the new (path, manifest) return shape and
  passes `command="manual"` + `dir_label=name`.
- Strings translated to English (the whole new subcommand group; the rest of
  the CLI stays Spanish — out of scope here).

Tests:
- test_snapshot.py: 21 unit tests (up from 14). New: round-trip across ALL FOUR
  artifacts (pr-test-analyzer #1 CRITICAL), millisecond-collision regression,
  corrupt-JSON-aborts-snapshot, dir_label separation from command,
  shutil.copy2-preserves-bytes (binary-safety smoke test), per-artifact action
  codes, xbrain_version assertion (pr-test-analyzer #5), prune-with-fewer-than-
  keep_last (pr-test-analyzer #6).
- test_snapshot_auto.py: 16 integration tests (up from 10). New: snapshot-
  taken-before-mutation-when-op-fails (pr-test-analyzer #2 CRITICAL — uses
  monkeypatch to force `_mark_for_regenerate` to raise, asserts snapshot
  already on disk + items.json unchanged), snapshot-failure-aborts-destructive-op
  (pr-test-analyzer #3 CRITICAL — monkeypatch snapshot_create to raise OSError,
  assert fetch --force aborts and nothing is mutated), snapshot show CLI
  (pr-test-analyzer #7), restore-via-CLI-with-missing-artifact
  (pr-test-analyzer #8), corrupt-dirs-marked-via-CLI, stdout-includes-item-count
  (pr-test-analyzer #10).
- All 258 tests pass; coverage 87%.

CONTRIBUTING.md:
- Added a "Safety: destructive operations auto-snapshot" section
  (spec-compliance #FAIL — closes the doc gap).

Deviation log unchanged: 3 destructive sites (`vocab --regenerate`,
`topics --resynth`, `fetch --force`) — `enrich --regenerate` does not exist
as a CLI flag, re-enrichment happens via `vocab --regenerate` which is
already covered. Spec-compliance reviewer confirmed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
VGonPa added a commit that referenced this pull request May 24, 2026
@VGonPa
[#33] document Phase A media downloader in README + ARCHITECTURE
9d2540b 
README:
- Add `media` row to the Commands table.
- New "Local media storage" section covering on-disk layout
  (`data/media/<id>/<n>.<ext>`), vault rendering convention
  (mirrored into `<output_subdir>/_media/` for self-contained
  embeds), disk budget guidance, throttling, and the
  transient/permanent failure-retry contract.

ARCHITECTURE:
- New "media" entry under per-stage detail (state machine,
  Ctrl-C safety, snapshot trigger).
- Artifacts table row for `media/<id>/<n>.<ext>`.
- Invariant #10: media variants are mutually exclusive states;
  state transitions only via `xbrain media`; legacy `{type, url}`
  records migrate on read.

Refs #33
VGonPa added a commit that referenced this pull request May 24, 2026
@VGonPa
[#33] strip issue-number rot and rewrite lying docstrings
6399f37 
- Strip `Phase A`, `Phase B`, `(#33)`, `pre-#33`, `pre-Phase-A` markers
  from new/modified code, docstrings, and tests. Also strip `(#17)`,
  `(#19)`, `(#20)`, `(#24)` references added in this PR's diff. The PR
  description carries the issue link; code should describe lasting
  invariants, not the PR that introduced them.
- Rewrite `_TRANSIENT_MEDIA_FAILURES` cross-reference comment: was
  `_TRANSIENT_FAILURES` (the actual symbol in fetch.py).
- Reword `Failed(transient)` "terminal-ish" phrasing in ARCHITECTURE.md
  `### media` — `Failed(transient)` IS auto-retried; not terminal.
- Reconcile snapshot/media docs: snapshots cover only the four JSON
  artifacts; photo bytes under `data/media/` are NOT snapshotted today.
  Updated `config.py:media_dir` docstring and ARCHITECTURE.md to make
  the carve-out explicit; re-downloading is the recovery path.
- Trim ARCHITECTURE.md invariant #10 to match the brief style of
  invariants #1-#9. Retry contract and storage layout moved to the
  `### media` section above (now with storage layout subsection).
- Trim the `media` row in README.md Commands table to one sentence with
  a link to `Local media storage`. Mark the disk-budget numbers as
  approximate.
@VGonPa VGonPa mentioned this pull request May 24, 2026
Merged
20 tasks
VGonPa added a commit that referenced this pull request May 24, 2026
@VGonPa @claude
[#34] update README + ARCHITECTURE for the describe stage
d71a30a 
README grows a Commands row for describe, a Configuration row for
[describe].model and [describe].version, and a Vision descriptions
subsection in the Local media storage section that explains the
$3-5 budget, the decorative-filter, and the description-version
re-describe trigger.

ARCHITECTURE adds a Per-stage describe section between fetch and
vocab covering the state machine, batching, refusal handling,
failure isolation, snapshot trigger, and the consumption seam in
executors/api.py + topic_synth.py. The rubrics table grows a
describe-image row; invariant #10 names the fifth Media variant and
makes the linear-pipeline shape explicit (Pending → Downloaded →
Described, with Failed as the off-ramp from Pending).

Also bundles two formatter-only cleanups picked up by ruff format
on the executors/api.py and topics.py changes from the prompt
integration commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@VGonPa