X Bookmark Artifact Audit
Deterministic queue for reviewing every X bookmark one by one across enriched records, resolved links, self-threads, artifact replies, local images, video demos, and capsule promotion.
Run:
npm run audit:x-bookmark-artifacts
npm run audit:x-bookmark-artifacts -- --limit 25
npm run audit:x-bookmark-artifacts -- --ids 123,456
Outputs:
| Output | Purpose |
|---|---|
wiki/meta/x-bookmark-artifact-audit.json |
Tracked per-bookmark ledger. Preserves manual review fields across reruns. |
outputs/bookmark-absorb/artifact-audit-YYYY-MM-DD.md |
Human next-review queue. |
outputs/bookmark-absorb/artifact-audit-YYYY-MM-DD.json |
Full machine-readable snapshot for the run. |
What It Catches
The old coverage audit proves that a bookmark is referenced somewhere in the wiki. That is necessary but not enough. A bookmark can be "covered" while its image was never inspected, its self-thread was never read, its artifact reply was skipped, or its resolved article never promoted into a tool/concept/skill page.
This audit separates those states:
| Flag | Meaning |
|---|---|
source-review-required |
Resolved links, self-thread items, or artifact replies need inspection. |
visual-review-required |
Local images or expected media need vision/OCR review. |
video-demo-review-required |
A video demo exists and must be linked or preserved if source-critical. |
missing-local-image:* |
Enriched media says images exist but local assets are incomplete. |
missing-local-asset:* |
Manifest points to a file that is absent. |
empty-local-asset:* |
Local media file exists but has zero bytes. |
manifest-byte-count-stale:* |
Manifest has bytes: 0 but the local file is non-empty. |
no-direct-wiki-reference |
The bookmark does not yet have a direct wiki reference, even if its thread/conversation may be covered elsewhere. |
Review Contract
For each high-priority row:
- Read
raw/x-bookmarks/enriched/<id>.json. - Inspect resolved links and child links.
- Inspect self-thread and artifact replies.
- Open local images with vision/OCR when visual review is flagged.
- Link video demos or download them only when source-critical.
- Promote durable thoughts into wiki pages, tools, concepts, philosophies, skills, playbooks, diagrams, or person pages.
- Update the relevant capsule source pages and rerun
npm run agent-packs. - Follow Generated Surface Contract when the review changes packs, capsules, skill registry output, redirects, qmd, or the stateful audit ledger.
- Preserve review notes in
wiki/meta/x-bookmark-artifact-audit.json:reviewStatus,reviewedAt,reviewedBy,reviewedArtifacts,visualObservation,thoughtNotes,promotedPages, and structureddecisions.
Decision Fields
A completed row is not just reviewStatus: reviewed. It must say what the
bookmark did to the brain:
| Field | Meaning |
|---|---|
decisions.articles |
Whether to create, update, merge, keep hub-only, or make no article change. |
decisions.skills |
Whether to create/update an executable skill, keep a candidate/reference, or make no skill change. |
decisions.tools |
Whether a tool page, routing entry, or version snapshot changed. |
decisions.capsules |
Whether brain capsules or generated packs changed. |
decisions.versioning |
Whether version/release research was done, deferred, or not applicable. |
decisions.rationale |
Short reason for the row-level call. |
reviewedArtifacts |
Evidence that the enriched record, links, thread, replies, images, or videos were actually inspected. |
Valid decision values are create, update, hub-only, candidate, merge,
no-change, not-applicable, and defer.
Run the gate:
npx tsx scripts/doctor.ts --only x-bookmarks
The doctor fails when the source or ledger is broken and warns while individual bookmark decisions remain pending. This makes the 800+ row review durable across sessions without pretending that hub coverage equals learning.
The ledger is intentionally tracked because the 800+ bookmark review spans many sessions. Agents should never restart the review from scratch or claim the full corpus is reviewed without the ledger proving it.
Timeline
- 2026-07-01 | Added generated-surface closeout to the bookmark review contract so artifact decisions update source pages, packs, capsules, qmd, redirects, and the stateful ledger coherently. Source: User request, 2026-07-01
- 2026-06-30 | Added structured per-bookmark decision fields and the
x-bookmarksdoctor gate so completed reviews must record article, skill, tool, capsule, and versioning outcomes. Source: User request, 2026-06-30;scripts/doctor.ts - 2026-06-29 | Created after Kevin requested a literal one-by-one pass over 800+ X bookmarks, including artifacts and images, because previous ingestion was too shallow and did not produce enough learning, skills, tools, articles, or capsule updates. Source: User request, 2026-06-29