WOM

Widesider of Modernity: a local-first, AI-native, Web3-oriented archive and communication system for widening the horizon of human perception.

한국어 README · Documentation Map · Upgrade Guide · Changelog · Release Notes · Security · Disclaimer

WOM stands for Widesider of Modernity.

The name expresses the ambition to stand near the frontier of modernity and widen the horizon that humans can perceive.

Inside WOM:

• zettel-kasten is the historical root and local archive method,
• zet is the unit document minted inside a zettel-kasten,
• header is refs, hashes, provenance, policy, and receipts around a zet,
• block is zet + header,
• ZET is the zettel-kasten-based communication layer that can become messaging, SNS/feed, or collaboration,
• node is the subject/archive participant,
• the preferred lifecycle is mint -> delegate -> attest -> anchor.

zettel-kasten remains the repository and archive-system root, but the product language should center WOM, zet, ZET, and node.

Status

Current public baseline:

v0.3.263 pre-release

Previous public baseline: v0.3.262 pre-release.

Full release history: see CHANGELOG.md and wom-kit/docs/releases/.

This repository is a public showcase and reference implementation workspace. It is not production-ready yet.

Roadmap snapshot: v0.1.x was the idea/protocol-language line, v0.2.x was the first local implementation line, v0.3.x is the current WOM real-use feedback and safety-hardening line, v0.4.x is planned for the custom UI control layer, and v0.5.x is planned for ZET real-use feedback. See the WOM Product Roadmap for the phase gates and future-only boundaries.

Quick Start

Install the exact release wheel as an isolated command-line tool:

uv tool install "https://github.com/mow-coding/zettel-kasten/releases/download/v0.3.263/wom_kit-0.3.263-py3-none-any.whl"
archive --version

WOM-kit is not published to PyPI yet, so bare pip install wom-kit is not an official install path. Plain pip is supported only in a dedicated virtual environment using the exact release wheel. Installing the Python tool does not open or change an archive and does not silently edit AI-host settings.

The wheel includes the wom-archive Agent Skill. Preview activation for the current Codex user before approving any host-configuration write:

archive runtime-skill-install --dry-run --format json

Continue with the Python tool install guide, the Korean install guide, or the Agent Skill activation and removal guide.

What Exists Today

Shipped surfaces, grouped by theme. Each bullet is one shipped capability; for the status-by-capability view (real implementation, read-only preview, approval-gated write, or docs-only), see the WOM-kit Capability Matrix.

Archive core & lifecycle

• a public WOM/zet/ZET design baseline with specs, schemas, fake archives, release notes, and work logs,
• an artifact-first human-memory doctrine: time-situated local artifacts and their chronology outrank regenerable entity/graph projections; matching labels never authorize silent identity merges, canonical names the subject-approved current archive state rather than objective truth, and AI may re-infer context while human change remains visible; see Product Philosophy and the claim-by-claim Philosophy Implementation Evidence,
• a public version-line roadmap that explains how the pre-1.0 minor lines map to idea, implementation, WOM feedback, UI/control-layer, and ZET feedback phases,
• a machine-readable local-sovereignty contract: local reviewed WOM state is canonical, GitHub backs up metadata/version history, object storage backs up objet bytes, and external databases hold regenerable map backups or replicas; runtime/start-here/recovery surfaces share the same offline, conflict, recovery, and receipt boundaries, while read-only backup-evidence reports only locally verifiable lane evidence and never turns local commits, declared labels, generated indexes, or receipt-time coverage into a false current-remote or whole-backup claim,
• WOM-kit local CLI and MCP tooling under wom-kit/, importing as wom_kit,
• a self-contained v0.3.242 Python wheel whose exact GitHub release artifact carries the runtime schemas, templates, base rules, and release identity needed for clean-environment onboarding and strict Doctor; isolated uv tool install is recommended, a dedicated pip virtual environment is supported, and PyPI publication remains explicitly future work,
• private archive lifecycle tools for doctor checks, draft creation (with forward-only draft-id hygiene so a titleless or Hangul-only title no longer yields a misleading _draft id, and draft-time --kind validation that warns and lists valid kinds), minting with dry-run checklist guidance and an attributed --affirm flag that satisfies the two human-review checklist items via an audited, reviewer-attributed CLI act instead of a raw YAML edit (recorded in the mint receipt, inert without --reviewed-by, never overriding machine-enforced items), verified minted-draft retirement, delegation, receipts, search, and metadata review,
• honest archive remint-reconcile (and the sibling archive retire-draft-reconcile for retire receipts) that re-issues a receipt's recorded sha256 after a zet drifts on disk (a CRLF/BOM re-checkout or a human content edit): it classifies the drift as newline/BOM-only format_drift or content_change even when the draft snapshot itself drifted — checking every content frontmatter field (a full-field reconstruction plus an id/title cross-check against the mint receipt) so an edit to any field, or a content-tampered snapshot, can never anchor format_drift — always shows the on-disk content, requires a reviewer to approve, offers an opt-in --strip-bom that never bypasses the content-change ack gate (and, since v0.3.172, previews the same strip-intent metadata on a dry-run as an approve run records — a strict classification no-op that never launders a content_change), surfaces (since v0.3.176) a content-free body_diff_diagnostic on a content_change whose body still differs after the BOM/newline fold — a category label plus a normalized-form byte offset and length delta, never any body text — and now offers dry-run JSON --diagnostic-only to omit canonical body text and frontmatter values while preserving those drift numbers; since v0.3.230, every content_change also returns a content-free ordered human-review plan and requires its SHA-256 again at approval, so changed bytes or receipt refs invalidate stale approval before any write, never masks corruption, and writes both an in-place receipt update and a separate immutable audit receipt,
• reconcile approve results now report status: reconcile_applied with doctor verification next-actions, so an applied approval no longer carries the earlier dry-run review status in JSON or text output,
• object-storage doctor now accepts same-key skipped_remote_same coverage, offers approval-gated object-storage-wom-location-reconcile for genuine missing wom_uploaded manifest bindings, and validates that command's audit receipts with a dedicated schema,
• generated-index-backed duplicate checks, metadata-backed mint staleness fast paths, SQLite busy-timeout/WAL hardening for generated-index write paths, and standard-id source-path fast resolution for large archives,
• scoped validate --since / validate --scope checks with generated-index body SHA cache support and optional --progress, plus stage/count progress output for long doctor --strict, large object-storage-adopt-existing, and staged-cleanup-check runs; large adopt plan resolution now uses a per-run manifest index, explicit --skip-existing-wom-uploaded resume helper, read-only --stop-after-plan diagnostics, resume-gap counts for matching declared_uploaded versus wom_uploaded locations, same-provider nonmatching store/key diagnostics, and same-store wom_uploaded raw-vs-gating counts, doctor reuses per-run file SHA/frontmatter caches and reports deeper mint-receipts target-frontmatter, mint-link, receipt-completion progress, every-receipt heartbeat, every-receipt file-ref liveness, target file-ref drilldown, target edge-receipt index lifecycle plus aggregate source/candidate/cache-hit heartbeats and a final summary, hash start/end liveness, retired-source skips, local-profile secret-safety liveness, early ETA warm-up, compact default --progress, opt-in verbose tracing, JSONL progress logs, full result capture with archive-relative --output, compact summaries, stdout severity filters, output/progress-log path-policy metadata, and staged cleanup can show content-free walk/verify/hash progress while remaining report-only; per-source edge candidate details stay in verbose/JSONL output instead of flooding compact stderr, while ai-start-here, upgrade-check, and CLI zet-catalog share content-free progress, 10-second heartbeat, and scratch-scoped full-result output; zet-catalog-pass completes all strict pages in one process with ephemeral memory reuse and final local revalidation before publishing one SHA-pinned private scratch JSONL, zet-catalog-pass-read validates that whole artifact before returning one bounded page, and zet-catalog-pass-cleanup deletes only the matching complete scratch file after preview and explicit human approval,
• completed full-Doctor handoffs retain bounded ERROR/WARN items, complete code counts, and suggested commands instead of collapsing actionable findings to severity totals; a BOM finding now fills its reconcile dry-run with the validated canonical zet id and omits the command when that id is absent or unsafe instead of emitting an unresolved placeholder; compact heartbeat prioritizes the current local-profile secret-safety file/content/profile counts over a preserved older edge aggregate, and the regular-file safety walk reuses its checked directory boundary while keeping strict symlink escape checks,
• read-only archive zet-quality-check --dry-run for entity-term, document-type, OCR/parse metadata, table-structure, correction-event, source-rights, audience, and derived-artifact dependency risks before mint; optional zet-quality-rules.yml project rules can make forbidden entity aliases mint blockers without echoing matched terms,
• read-only archive status-board --dry-run for beginner-facing archive state counts across canonical zets, active drafts, minted drafts pending retire, document/audience metadata gaps, source metadata gaps, derived-artifact sync gaps, and optional body-inspecting quality counts without echoing titles, bodies, source values, provider URLs, or local paths,
• frontmatter-only archive first-read-readiness --dry-run and MCP first_read_readiness separate ordinary archive health from AI memory-reconstruction readiness: every non-redacted canonical zet needs an explicit abstract and every selected zet needs a uniquely resolvable safe id before the gate says ready; compatibility text and bounded content-free repair candidates remain visible without echoing titles, abstracts, bodies, duplicate-id values, absolute paths, provider values, or secrets; create-draft may still preserve an incomplete idea without an abstract, while mint-zet, mint-zettel, and legacy promote require and revalidate one explicit safe abstract before any canonical publication write; read-only archive abstract-freshness --dry-run and MCP abstract_freshness then compare each current abstract/body hash pair with retained human-review evidence, distinguish fresh, stale, unverified, missing, unreadable, and policy-excluded zets in one receipt-index plus one canonical pass, and never echo text or auto-rewrite memory; read-only archive zet-revision-plan --dry-run and MCP zet_revision_plan bind one private full-zet correction proposal under .wom-scratch/revisions/ to the exact current canonical bytes, freeze identity/lifecycle/creator metadata, and return only hashes plus fixed change categories; CLI-only archive zet-revision-write --dry-run|--approve then adds an exact writer-candidate digest, explicit human review gates, exact prior-byte preservation in the local content-addressed objet store, atomic replacement, runtime rollback, interruption-safe receipt completion, and one immutable text-free v0.2 revision receipt that also restores abstract-freshness evidence; read-only CLI archive zet-revision-receipt-audit --dry-run orders ordinary corrections and exact restores as one strictly chained event history, verifies new prior-byte snapshots and their manifest records, permits evidence-complete repeated states such as A -> B -> A, and classifies leftover transaction locks without deleting them or echoing private content; CLI-only archive zet-revision-restore-proposal-from-snapshot --dry-run|--approve first creates an independent content-addressed private review proposal from a verified v0.2 prior-byte snapshot without changing canonical memory; CLI-only archive zet-revision-restore-plan --dry-run binds separately recovered complete old zet bytes to the actual latest receipt event and reapplies current policy, while separate approval-gated archive zet-revision-restore-write --dry-run|--approve atomically installs only those exact reviewed bytes, preserves their historical formatting and updated_at, rolls back handled failures, resumes interrupted transactions, and appends one immutable text-free restore receipt; this is one layer of WOM's answer to the Memento Problem: a new AI session should rebuild, correct, and when necessary perform evidence-backed recovery of durable context through reviewed local artifacts instead of trusting a fading chat session or editing memory without evidence; since v0.3.240, first-read diagnostic completion is separate from readiness, freshness opens only current evidence candidates without a persistent cache, two-stage progress names the remaining phase, and a large legacy gap starts with a three-zet human pilot rather than bulk automatic backfill; since v0.3.241, freshness scans bounded frontmatter through at most eight workers and opens complete body bytes only for valid explicit-abstract targets,
• read-only archive derived-artifact-staleness --dry-run for checking whether declared derived_artifacts may be stale because a source zet is newer than the artifact's last reviewed sync. It writes nothing, opens no external report, and does not echo artifact refs, titles, bodies, provider URLs, or local paths,
• a v0.2.x freeze / v0.3.0 entry boundary document plus a narrow v0.3.0 write boundary that stays local-first and body-safe,

Capture & intake

• human-guided project intake planning, decision receipts, source-intake context, and objet-capture receipt gates,
• a normative AI intake protocol on every runtime-visible surface (AGENTS.md templates, the runtime SKILL.md, and the skill/plugin layer doc),
• source-intake dry-run BEFORE physically copying any local file into the archive or an objet store, with in-archive staging/incoming/ capture staging as the canonical intake location (D2),
• reviewed selection -> approved capture as the only capture authority, plus prehashed-ledger evidence for bulk external stores,
• two additive read-only doctor guards (archive_objets_layout_noncanonical for a raw in-root objets/ folder with a documented migration guide, and workspace_objet_store_git_exposure when an objet byte store may be tracked by an enclosing git working tree) plus the anchored /objets/ .gitignore safe default,
• paired transcript intake through archive objet-capture-selection --derived-text-staged-path: one reviewed selection manifest approves both a staged original and its already-extracted transcript (raw-byte approved_text_sha256 commitment, full staged-path-parity confinement),
• one archive objet-capture run that publishes the original and registers the derived text bound to the minted object_id, with additive item/run status_class (partial = original durable, derived retriable),
• BOM-aware derive-text decoding (BOM-marked UTF-8/UTF-16 stored as BOM-less UTF-8 with raw-byte provenance; UTF-32 and BOM-less non-UTF-8 block deterministically),
• owner-approved real-archive objet capture enablement through archive objet-capture-enable: a read-only dry-run eligibility report and an approval-gated singleton ops/capture-enablement.yml consent record with a receipt trail, so a real (non-sandbox) archive can run local objet capture only after explicit, receipted, revocable owner consent,
• explicit never-touch name acknowledgment, forward-only revocation with --reenable protection, and doctor visibility for that consent record; the record is a consent marker in the same write-trust domain, not a security boundary,
• read-only derived-text coverage/toolchain/doctor/agent-contract gates, manifest-scoped completeness signals, and manifest-quality checks that block false complete claims when tool_version or required extraction metadata is missing,
• existing derived-text records as a fallback textual signal for older prehashed manifests, plus non-echoed tool-hint paths for PATH-missing local extractors,
• approval-gated single-file and JSONL batch derived text capture for registering already extracted parser/OCR/ASR/vision text against source objets,

Retrieval & views

• read-only preview layers for runtime context, profiles, source/objet intake, overview-first zet reading plus a human document view that hides raw YAML frontmatter, block headers with first-read summaries, and prompt boundaries; optional bounded frontmatter.abstract plus CLI/MCP zet-catalog enumerate every local zet with compact abstract-plus-tie reading, strict snapshot/token-budgeted zet coverage, measured item/service-result/response-envelope cost plus an opt-in envelope reserve, a required full first page followed by optional compact continuation responses that omit only repeated diagnostics, optional verified-seed connection order, and opt-in routed_reading explanations for each seed/tie/disconnected-component step, while separate readiness signals distinguish complete zet visitation, readable non-redacted abstracts, and unique id follow-up without requiring a generated index/map or creating persistent WOM-owned goal/loop state; non-redacted read-zettel supplies exact file/body hashes for the version actually read and supports opt-in Unicode character pages whose continuations are bound to the first page's complete body hash, zet-abstract-backfill-plan validates bounded private missing-abstract proposals, approval-gated zet-abstract-backfill-write applies only human-reviewed SHA-bound abstracts with a text-free receipt and whole-batch runtime rollback, receipt-bound zet-abstract-backfill-revert restores exact pre-backfill bytes only when no later canonical edit exists, and archive-wide zet-abstract-backfill-receipt-audit verifies every apply/revert lifecycle plus leftover crash-signal lock with bounded content-free output,
• generated index health checks, saved view health, facet role diagnostics, saved view recommendations,
• read-only objet reference resolution, presigned URL planning, and zettel objet link previews for mapping sha256:<hex> refs to safe local/external candidates,

Sharing & ZET previews

• read-only previews for foreign block review, projection planning with supported-surface help, shared update review/index, shared update route pointers, and ZET would-transport planning,
• approval-gated local write paths for selected private archive, foreign-block review records, and the first v0.3.0 shared update attestation/review record,

Privacy & redaction

• zet self-contained checks, AI scratch lifecycle management, and read-only AI artifact inventory introduced in v0.3.187 pre-release: public external citation URLs may stay in zet bodies or source_refs, private provider locators and original-file locations still require durable WOM refs, .wom-scratch/, workbench/ai-scratch/, staging/ai/inbox/, and staging/ai/reviewed/ are treated as bounded AI artifact/scratch surfaces, archive ai-artifact-inventory --dry-run can list candidate fates without reading file bodies, echoing paths by default, writing files, deleting files, creating zets, or calling providers, and approved mint can remove explicit scratch refs from the canonical zet while consuming those scratch files through a cleanup receipt,
• read-only archive secret-signal-taxonomy --dry-run for AI operators that need to distinguish harmless secret/credential/token concept words and safe refs from actual secret-like values, private locators, account identifiers, or unknown sensitive context,

AI-operator contracts & runtime handoff

• an optional MOW Harness compatibility boundary that keeps collab/ and .mow-harness/ local-only, leaves WOM usable without the Harness, and separates external read-only preview from separately approved update and activation,
• a CLI-only local Agent Skill host lifecycle: read-only runtime-skill-status, digest-bound runtime-skill-install --dry-run|--approve, and manifest-verified runtime-skill-uninstall --dry-run|--approve use current Codex user/repository .agents/skills locations or one explicit custom root, redact paths by default, require a reviewer plus the exact preview digest before writes, and never overwrite or remove unmanaged/human-edited skill directories; Python installation itself still writes no host configuration and no MCP write surface is added,
• a standards-compatible wom-archive Agent Skill package with a 104-line first-read SKILL.md, six focused task references, one preserved complete operator contract, and a release-gated validator for metadata, link/path safety, discovery, context budgets, approval/privacy boundaries, artifact primacy, and no-silent-identity-merge guidance; AI operators load only the reference needed for the current goal, treat canonical as reviewed state rather than objective truth, preserve human change, and never install themselves silently,
• read-only WOM-kit version truth-source checks through archive --version, archive version --format json, parent project installed-version pin discovery from archive roots, and runtime-context version metadata, plus approval-gated project-version-update for an atomic configured-origin fetch, verified exact-tag detached checkout, recognized pin alignment, rollback, receipt, and mandatory new-process verification without touching archive knowledge,
• read-only archive capabilities --machine for AI operators that need a stable ok/state/summary/data/blockers/warnings envelope listing the executable local CLI commands, aliases, required positionals, options, nested subcommands, and local release identity without calling GitHub or providers,
• read-only archive operator-feedback-plan --dry-run and approval-gated archive operator-feedback-record --approve for tracking operator-generated tool feedback under ops/feedback/ with draft/delivered/acknowledged/resolved/archived lifecycle metadata, plus read-only archive operator-feedback-ledger --dry-run (aliases feedback-ledger, feedback-board) that aggregates delivery-status counts + a pending list and approval-gated archive operator-feedback-mark-delivered --approve that batches the draft->delivered boundary with a delivered_at stamp and a single receipt, all without reading feedback bodies, echoing feedback refs/titles, submitting externally (metadata only; delivered is the operator's own mark, not proof of external delivery), or mixing feedback lifecycle state into user knowledge objets/,
• read-only archive approval-handoff-plan --dry-run and approval-gated archive approval-handoff-record --approve for AI-to-human approval handoff metadata under ops/approval-handoffs/, so sensitive operations can stop at a clear needs_review/approved_once/denied/superseded/resolved state without executing the operation, reading private material, calling providers, or echoing target/action values,
• read-only archive approval-handoff-audit --dry-run for checking a handoff record before a future operation uses it as approval evidence, without executing the operation or echoing target/action values,
• read-only archive operation-status-taxonomy --dry-run for AI operators that need to distinguish succeeded/preview/written/no_change from partial/truncated/blocked/failed results before telling a human that work is complete,
• read-only archive input-provenance-taxonomy --dry-run for AI operators that need to distinguish tool-discovered and receipt-verified inputs from caller-supplied, AI-generated, fixture, environment-inferred, or unknown inputs before treating them as source truth,
• read-only archive ai-response-contract --dry-run for AI operators that need a conversational status-board contract before answering a human: outcome, evidence basis, privacy/approval boundary, remaining work, and no web UI requirement,
• core read-only operator commands now expose top-level status_class, input_provenance_class, secret_signal_class, and operator_envelope fields so AI operators can apply the response contract without inferring those classes from prose,
• runtime-context canonical entrypoint metadata so AI runtimes can see which archive-relative files/directories to treat as start-here and authoritative sources, plus machine-readable ai_runtime_order, recommended_first_commands, and material_link_routes that hand off from runtime-context to AGENTS.md and ai-response-concept-guide,
• read-only archive ai-start-here <archive-root> --dry-run --format markdown|json and quick-default CLI/MCP runtime-context project identity, canonical entrypoints, authority, operational context, and cross-file identity consistency without walking every zet or receipt; complete Doctor work is explicit through --full-doctor, its edge-receipt evolution check builds one filename-only index and opens only receipts belonging to the mismatched zet while reporting separate content-free index/load counts, start-here marks runtime-context as already included while exposing separate completed_commands and next_commands, new archives replace template identity metadata during initialization, and existing same-principal template/display mismatches route to the value-free identity-reconcile --dry-run plus an explicit three-digest-bound approval instead of a silent metadata rewrite,
• AI operational context rehydration through ops/operational-context.yml, runtime-context field operational_context, and approval-gated archive operational-context updates with receipts, so an AI runtime can recover mission, scope, state, gotchas, reviewed decisions, and next actions after context compression without reading broad archive bodies first,
• receipt-backed archive session-handoff-checkpoint for closing an AI session without trusting chat memory: it binds the exact approved operational-context bytes and a content-free AI artifact inventory into a stale-safe digest, requires explicit conversation review before approval, and becomes stale when either archive surface changes; it never reads the host chat or AI artifact bodies and is not remote backup proof,
• AI token usage observability through read-only archive ai-usage-plan --dry-run, approval-gated archive ai-usage-record --approve, and read-only archive ai-usage-report --dry-run, so WOM can estimate explicit context packs, record non-secret runtime token counters, and aggregate bottlenecks without storing prompts or responses,
• read-only archive ai-response-concept-guide --dry-run for beginner-facing AI explanation cards about sha256 object identity vs location, manifests vs zets, the objet -> derived text -> zet layer split, operational term translations for edge types, lifecycle states, and connection kinds including contains for structural child page/database containment, plus safe routing to Notion import material-clue audits, source-map material-link planning, connection import planning, nested tree recovery planning, and ancestor crawl request planning when provider locators were omitted from imported zettel bodies or structural relations need model review, without overclaiming upload, availability, stronger tie meaning, or forced edge-type mappings,
• ai-response-concept-guide --topic operator_vocabulary --locale ko-KR, a read-only vocabulary layer for AI operators that uses user-confirmed product terms (WOM, zet, ZET, objet, receipt as 영수증, mint as 발행하다, canonical as 정본, node as 노드, edge as 엣지, tie as 타이, archive as 아카이브 폴더, ai_start_here as AI 스타팅 메뉴얼, frontmatter as 초록 데이터) and confirmed operator terms such as object_id as 오브제 아이디, doctor as 검진, provider as 외부 서비스, containment as 포함 관계, safe_preview as 미리보기, approved_write as 승인 후 쓰기, external_report as 공개용 문서, and private_working_note as 비공개 문서,
• a normative plain-language convention on the operator-facing runtime surfaces (AGENTS.md templates, the runtime skill, and the plugin-layer doc) telling an operator AI to translate git/infrastructure/WOM-internal jargon into everyday language for humans while keeping the exact term in parentheses or logs, backed by a read-only ai-response-concept-guide --topic git_infra_terms lookup layer; it is guidance the AI applies in human-facing prose only, not a WOM-enforced check,
• a normative AI-Operator Discipline section on the same runtime surfaces stating three behavioral norms an operator AI applies: record the source the human actually encountered and never silently substitute a "more authoritative" one (with a matching source-substitution axis in the provenance hierarchy), enumerate the installed/available tools before declaring a task impossible or degrading it, and carry forward already-established/approved state instead of re-asking; it is guidance the AI applies, not a check WOM validates or enforces,

Provider integrations

Tiro:

• read-only Tiro meeting transcript import planning from archive-internal manifests, preserving meeting metadata, speaker turns, timestamps, confidence, and optional audio objet refs without echoing transcript text, participant names, source URLs, audio filenames, local paths, account ids, emails, tokens, or secrets,
• read-only Tiro full-data lossless recovery planning, approval-gated live Tiro REST fetch into a private raw bundle from env: or Windows Credential Manager-backed keyring: / credential-manager: refs, and approval-gated raw Tiro recovery bundle capture into WOM objets, preserving private raw bundle bytes while reporting only hashes, counts, archive-relative paths, and gap categories,

Notion:

• Notion nested recovery human-step guidance that translates low-level ancestor/fetch/fixture/merge terms into location-oriented user language before one-time approval and live structure fetch handoff,
• archive notion-recover with a local file:<path> token-file fallback that echoes neither the file path nor the token,
• archive notion-connection-plan --dry-run for the one-click Notion connection product contract, and archive notion-oauth-connection-preflight --dry-run for validating the secret-blind local OAuth runtime contract before any future browser/callback/token exchange flow,
• Notion provider failure classification into action categories such as token, permission/page-share, rate-limit, network, or provider-availability without raw error echo, while live browser OAuth, callback servers, token exchange, and keyring/vault token storage remain future adapter boundaries,
• read-only human artifact store planning for WordPress, Joplin, Notion, Obsidian, Evernote, generic Markdown, and generic workspace surfaces,
• text-first external export planning with explicit large-media trap detection before broad workspace/database downloads,
• approved external imports that preserve explicit safe object refs, safe source_refs, safe facets, and safe zettel id overrides from manifests into imported drafts, plus optional Notion body locator conversion to reviewed objet: refs,
• read-only Notion connection import planning for typed-edge candidates with base connection edge vocabulary including contains for structural child page/database/view containment and model-gap escalation when no active edge type fits,
• approval-gated link type migration for stale archive-local types.yml, plus receipt-backed safe link-types-v0.3 migration revert when the migration receipt says which edge types were added and those types remain unused and unchanged from the base template,
• approval-gated archive migrate --target base-link-types that appends every base WOM-kit link type missing from a vendored types.yml (a superset of the recommended-9 set, so it also pulls continues) without removing, renaming, reordering, or overwriting any existing entry — append-only, no-clobber, no revert, --reviewed-by-gated, safe no-op when the archive has no local types.yml (it already inherits the base), and honest that it normalizes the whole file via safe_dump like the sibling migration,
• a read-only connection evidence parser contract before real export parsing, and a sanitized fixture parser that emits candidate edge previews without writes,
• read-only connection edge intelligence planning that separates relationship meaning from source mechanism, distinguishes ambiguous candidates from human-review-required candidates, flags provisional candidates before human approval, and recommends supersedes for sanitized version-chain hints plus contains for sanitized containment hints,
• read-only Notion nested tree recovery planning that assigns leaf pages to known generation roots, derives safe content classes from node kinds when needed, blocks oversized nested-tree fixtures instead of returning partial success, and reports untraceable parent chains instead of guessing from partial mirrors,
• read-only Notion ancestor crawl request planning with generation/ref scope filters and a recursive fetch adapter execution contract, plus documentation that untraceable leaf recovery should be scoped by leaf/root/ancestor refs rather than generation id when the generation is still unknown,
• the first approval-gated local Notion ancestor structure fetch adapter, which writes only sanitized ancestor fixtures plus non-secret receipts after credential approval, while Notion media byte fetch and page body capture stay behind separate future gates,
• local nested-tree recovery tooling that builds nested tree fixture previews from reviewed block mirror metadata, merges sanitized ancestor result nodes with immediate after-merge replanning, verifies client nested-tree issues from sanitized local fixture bundles, and packages the minimal sanitized fixture request contract for client follow-up,
• documented Notion page snapshot and store-ref boundaries for page/block JSON exports,
• one-zettel plus archive-wide Notion provider locator to manifested objet link planning and reviewed rewrite planning without echoing provider URLs or creating provider URLs,
• import material-clue auditing plus scaled source-map/ledger based Notion material-link planning for imported zets whose body locators were already omitted,
• approval-gated Notion objet manifest locator fingerprint labels so reviewed manifests can match later locator plans without storing raw provider locator text, and approval-gated Notion locator conversion to reviewed embed edges without rewriting zettel body text,

Zettel edge writes:

• approval-gated single-edge zettel edge writes for reviewed zet-to-zet or zet-to-objet links including safe zet:notion:<id> target resolution,
• approval-gated policy batch zettel edge writes that route only high-confidence policy matches through the single-edge gate, reuse one preloaded object-manifest index for objet targets and one zettel id/path index for zet-target batches, leave the rest in a human review queue, resolve batch plans archive-relative first, and can skip already-written edge rows on explicit request,
• receipt-based revert-edge and revert-batch commands for approved edge rollback without deleting original receipts,

Object storage:

• manifest-aware object-storage recommendation matching with surfaced bucket names, exact next commands, and Cloudflare R2 setup field guidance,
• object-storage adapter readiness planning, operation request packaging, upload execution-contract planning, and presigned URL planning,
• approval-gated external upload evidence registration and read-only upload evidence auditing before live provider adapters,
• Stage 2 of the live upload adapter: a real hand-rolled AWS SigV4 R2/S3 transport behind a single networking seam (no new dependency), with bounded replayable single-PUT bodies, bounded streaming verification GETs, strict response-completeness evidence, disabled automatic redirects, a bounded retry loop, a hard cumulative PUT ceiling, whole-object re-download-and-hash verification, generation-safe preservation instead of unconditional mismatch DELETE, and a tiered tiny-first gate; live --approve still fails closed without env credentials, a met tiered gate, and endpoint/bucket, and stays unproven_against_live_provider until the first human-run live object,
• a selectable, recorded upload key strategy (--key-strategy sha256_content_addressed|prefix, default unchanged) plus a safe object-storage-adopt-existing command: objects already stored under an operator's own key layout are adopted only on a live HEAD proving presence + size-match at the recorded key, and under a live transport the executor always re-HEADs that recorded key before any skip (a 404 re-uploads, never a silent skip); an opt-in --key-map (JSONL sha256 -> exact remote key) adopts objects stored under the operator's own per-object extension when the content-addressed template cannot recover it, size still manifest-sourced and every key digest-bound and leak-guarded,
• verified adopt (HEAD-only) is decoupled from the upload 5 GiB tier proof: because adopt moves zero bytes, one prior verified tiny-first adopt unlocks a batch handover of any size (the wrong-key self-limit, declared-never-counts, and byte-identical upload tier ladder all hold),
• a live-verification --multipart-part-size override (with the --allow-tiny-parts acknowledgment, bounded [4096, 64 MiB], recorded in the receipt as effective_multipart_part_size_bytes) that, paired with a lowered --multipart-threshold, forces multipart on a small object to prove LIVE R2 multipart; it changes only handle.read() fragmentation and leaves the whole-object before-hash, HEAD-after full-object verify, generation-safe no-delete boundary, and leak gate unchanged,
• a live-verification --force-reupload that re-PUTs an already-present object (approval + reviewer gated, refused for a non-sha key, inert under --dry-run, corrupt-local still refused before any PUT), now also bypassing resume-ledger-only skips and failing closed with force_reupload_not_performed if no provider PUT is attempted, so a small forced multipart can prove upload tier2, which a real multipart (part_count>1) now satisfies alongside the existing 5 GiB path,

IMAP:

• read-only IMAP mailbox source planning, operation request packaging, schema-validated adapter manifest previews, and approval-gated local adapter manifest writes,
• IMAP adapter readiness checks, mailbox selection planning, adapter audit receipt previews, approval-gated local adapter audit receipt writes, adapter preflight checks, and adapter execution-contract planning,
• a first approval-gated local IMAP header metadata scan for Gmail, Naver, and generic IMAP account refs, plus an offline audit checkpoint for those header scan execution receipts,
• read-only material selection, capture request, capture execution-contract planning, and material capture approval audits, plus approval-gated non-secret material selection records and approval-gated material capture approval receipts before future body/attachment/derived-text work,

Credentials & setup guidance

• a read-only beginner setup manual with KeePassXC first-vault field walkthroughs, KeePassXC CSV bulk migration import/merge guidance, and Cloudflare R2 bucket/API-token field walkthroughs with Korean/English label hints and S3 credential-pair guidance,
• connected accounts bridge with separate credential-catalog status,
• read-only credential reference planning, inventory, and external store recommendation including account recovery and break-glass redundancy scenarios,
• vault onboarding planning, credential semantic extraction recipe with recovery-code/break-glass routing hints, and plaintext migration planning,
• future access broker planning, local approval receipt preview/write, credential policy checking, and KeePassXC command preflight,
• CLI-only KeePassXC write execution with non-secret execution receipts,
• credential adapter readiness planning, adapter manifest preview, and adapter audit receipt preview for mail, OpenAI API, OCR API, provider, object storage, and backup secrets,

Hygiene & release tooling

• archive-root boundary warnings in archive doctor for top-level web/app development artifacts and incomplete .git markers, plus .gitignore safe defaults for node_modules/, .next/, and .vercel/,
• approval-gated .gitignore repair for missing WOM-kit safe defaults,
• local public-release hygiene tools for links, Korean product language, privacy, release readiness, and branch-protection planning.

What Does Not Exist Yet

• production-grade installation and platform support,
• broad real OS keyring read/write adapters beyond the narrow approval-gated Tiro Windows Credential Manager read, secret retrieval for other providers, OAuth flows, OpenAI API calls, or paid OCR API calls,
• broad live provider sync beyond the first approval-gated local IMAP header scan and the first approval-gated local Notion ancestor structure fetch,
• broad IMAP ingestion beyond the first approval-gated header metadata scan: OAuth login, keyring/password-manager retrieval, non-inbox mailbox selection, message body capture, attachment capture, or email-derived text extraction,
• production ZET transport, sharing service, feed update, or mirroring delivery,
• real wallet creation, private-key custody, cryptographic signing, token mechanics, payments, staking, consensus, or blockchain integration,
• recommendation fetching, ranking, automatic neighbor feed updates, or provider-backed recommendation services,
• projection-plan apply/write behavior, projection receipts, WordPress publishing, or provider-specific publishing,
• real foreign block import/trust/apply, signed attestation statements, receiver-side acceptance, or automatic shared-block renewal,
• broad archive-wide AI scratch sweeps, complete prompt-injection prevention, full-auto execution, model training, backpropagation, Redis, queues, or background workers,
• stable v1.0.0 protocol guarantee.

Core Model

The base WOM archive model is:

source/original data + metadata + minted zets

In other words:

• source/original data is the evidence layer,
• metadata makes sources addressable and auditable,
• minted zets are human-approved archive memory.

The system starts from the archive node, not from a social app.

See Naming And Terminology for the current naming freeze.

For the full design philosophy, including the human data primitive model, AX rationale, and Web3-like ZET sharing model, see:

• Foundational Product Whitepaper
• Product Philosophy
• WOM Safe HTML Profile
• WOM Product Roadmap
• Korean Product Language Baseline
• Korean Product Language Hygiene
• WOM-kit Capability Matrix
• Agent Operator Capabilities Manifest
• Operator Feedback Lifecycle
• Approval Handoff Lifecycle
• Approval Handoff Audit
• Operation Status Taxonomy
• Input Provenance Taxonomy
• Secret Signal Taxonomy
• AI Response Contract
• Operator Envelope Classes
• Objet Capture Enablement
• Archive Status Board
• First-Read Readiness
• Explicit Abstract Publication Gate
• Abstract Freshness Check
• Three-zet Abstract Backfill Pilot
• Derived Artifact Staleness
• zet Quality Check
• Version Truth Source
• Project Version Update
• zet Catalog One-Process Pass
• Runtime Canonical Entry Points
• Derived Text Completeness Signal
• ZET Radio-Frequency Recommendation Model
• ZET Shared Update Record Baseline
• ZET Shared Update Record Review Preview
• ZET Shared Update Record Review Index
• Shared Update Attestation Review Write
• Shared Update Route Preview
• ZET Transport Threat Model
• v0.2.x Freeze And v0.3.0 Entry Boundary
• Public Release Link Hygiene
• Public Privacy Hygiene
• Release Readiness Gate
• Main Branch Protection Readiness
• Public Documentation Map
• Project Intake Cookbook
• Credential Store Contract
• Credential Ref Inventory And Onboarding
• Credential Store Recommendations
• Credential Vault Onboarding Plan
• Beginner Setup Manual
• Notion Connection Plan
• Notion OAuth Connection Preflight
• Notion Recover
• Tiro Import Plan
• Tiro Lossless Recovery
• zet Markdown Style Guide
• zet Frontmatter Viewer Contract
• Connected Accounts
• Credential Semantic Extraction Recipe
• Credential Plaintext Migration Plan
• Credential Access Broker Plan
• Credential Access Approval Plan
• Credential Policy Check
• Credential KeePassXC Command Plan
• Credential KeePassXC Write
• Credential Adapter Readiness Plan
• Credential Adapter Manifest Plan
• Credential Adapter Audit Plan
• Human Artifact Store Contract
• External Export Plan
• Connection Import Plan
• Connection Evidence Parser Contract
• Connection Evidence Fixture Parser
• Connection Edge Intelligence Plan
• Zettel Edge Write
• Zettel Edge Batch
• Object Storage Recommendations
• Object Storage Adapter Readiness Plan
• Object Storage Operation Request Plan
• Object Storage Adapter Execution Contract
• Object Storage Upload Evidence
• Object Storage Upload Evidence Audit
• IMAP Mailbox Source
• IMAP Mailbox Operation Request Plan
• IMAP Mailbox Adapter Manifest Plan
• IMAP Mailbox Adapter Manifest Write
• IMAP Mailbox Adapter Readiness Plan
• IMAP Mailbox Selection Plan
• IMAP Mailbox Adapter Audit Plan
• IMAP Mailbox Adapter Audit Write
• IMAP Mailbox Adapter Preflight Plan
• IMAP Mailbox Adapter Execution Contract
• IMAP Mailbox Header Metadata Scan
• IMAP Mailbox Header Scan Receipt Audit
• IMAP Mailbox Material Selection Plan
• IMAP Mailbox Material Selection Record
• IMAP Mailbox Material Capture Request Plan
• IMAP Mailbox Material Capture Execution Contract
• IMAP Mailbox Material Capture Approval Plan
• IMAP Mailbox Material Capture Approval Audit
• Notion Page Snapshot Model
• Objet Ref Resolution
• Presigned URL Plan
• Zettel Objet Links
• Notion Objet Link Plan
• Notion Objet Link Index
• Notion Objet Import Clue Audit
• Notion Objet Source Map Link Plan
• Notion Objet Link Rewrite Plan
• Notion Objet Link Convert
• Notion Objet Manifest Locator Label
• View Health
• View Recommendation Plan
• Index Health
• Derived Text Coverage And Toolchain

The public project records are intentionally separated into:

product blueprint / design philosophy
implementation reference research
implementation plans
work logs

What Is zet?

A zet is always text.

It is a document created by a human, or drafted by AI under human supervision, then minted into a private archive.

In v0.2, zets remain Markdown-compatible for authoring and import compatibility. The long-term canonical/interchange/rendering target is the WOM Safe HTML Profile, not arbitrary HTML.

Minting means:

draft zet -> human review -> canonical private archive record

Minting does not mean public posting. External sharing is a separate action.

Why This Matters

Most tools make users adapt to an application.

WOM takes the opposite direction:

the user's archive stays primary,
AI helps draft and connect memory,
sharing is a deliberate projection from private memory.

The future ZET communication layer follows this projection model:

1:1 ZET relation       -> messenger
1:many ZET relation    -> social feed / SNS
many:many ZET relation -> collaboration workspace

Storage Model

Objet storage is not only for media files.

In WOM product language, source/original files stored outside Git are objets. Cloud and provider APIs may still call the technical storage layer object storage.

Original documents and captures are source objects when they are used as evidence:

• .hwp
• .hwpx
• .docx
• .xlsx
• .pdf
• .txt
• .md
• .csv
• screenshots
• audio/video
• provider exports
• provider page/block snapshot JSON

Recommended default:

original source files -> local objet store and/or object storage provider
object identity       -> object manifest
derived text          -> provenance-aware derived text records
zets and metadata     -> Git repository
search text           -> SQLite/search index

See Source Object Storage Policy. For Notion page/block exports, see Notion Page Snapshot Model.

For provider setup metadata, WOM-kit can also run a local receipt consistency check:

archive provider-status <archive-root> --dry-run

This CLI command, and the matching MCP provider_setup_status tool, check provider-bindings.yml against local provider setup receipts. They do not call GitHub, create buckets, upload files, push remotes, or verify live provider account state.

Text Provenance

Not every text artifact has the same authority.

WOM distinguishes:

L0 original source object
L1 born-digital editable text
L2 parser-extracted text
L3 OCR / speech-to-text / AI transcription
L4 human-reviewed derived text
L5 minted zet

OCR and AI transcription are useful, but they are model-dependent derived records. They should keep source object id, derivation method, tool/model version, confidence when available, and review status.

See Text Provenance Hierarchy.

Versioning

WOM, zettel-kasten, zet, and ZET are managed as a versioned protocol family.

Release tags are compatibility checkpoints:

v0.3.263 (current checkpoint)

Public releases from v0.2.5 onward are tagged as compatibility checkpoints. The full release history lives in CHANGELOG.md and the GitHub releases page; VERSIONING.md explains the versioning policy.

Notable compatibility checkpoints in the v0.3.x line include the v0.3.137 pre-release, v0.3.134 pre-release, v0.3.133 pre-release, v0.3.123 pre-release, v0.3.122 pre-release, v0.3.117 pre-release, and v0.3.116 pre-release baselines, the v0.3.109 pre-release edge-write baseline, and the v0.3.87 pre-release compatibility checkpoint. The v0.2.x line closed at v0.2.60, with v0.2.57, v0.2.56, v0.2.55, and v0.2.54 as the late v0.2.x checkpoints before the freeze.

Same major protocol version should mean expected compatibility. Different major versions may need migration or compatibility bridges.

See Versioning and Upgrade Guide.

Repository Layout

wom-kit/
  specs/        product and protocol specifications
  docs/         setup, security, onboarding, release, and operating notes
  plans/        implementation plans and public-safe work logs
  schemas/      JSON Schema files
  src/          Python package code
  cli/          local CLI entrypoint
  examples/     fake sample archive data
  templates/    personal, family, and company archive templates

Documentation Map

The public documentation is organized by purpose:

• product blueprint / design philosophy: Documentation Map
• implementation reference research: Implementation Research
• implementation plans: Plans Directory
• work logs: Work Logs

Start with Public Documentation Map if you want to understand the project before reading code.

Quick Verification

cd wom-kit
python -m unittest discover -s tests
python cli/archive.py doctor examples/fake-life-archive --strict

Expected result:

tests pass
doctor reports 0 errors and 0 warnings

Privacy Boundary

This public repository is not a real user archive.

Do not commit:

• provider tokens,
• local credentials,
• real private zets,
• real source maps,
• real receipts,
• private AI conversations,
• personal files or media,
• local machine paths or private filenames.

Real usage should happen in a private archive repository and separate objet storage/object storage provider.

See Open Source Publication Model.

Authorship

Original concept, product philosophy, naming, written design, schemas, and reference implementation:

Kim Seong Kyun (김성균)
Department of Urban Sociology, University of Seoul
GitHub: mow-coding
Email: mow.coding@gmail.com
Email: ellie0129@uos.ac.kr

If this project helps you, a GitHub star is appreciated. Collaboration and investment inquiries are welcome by email.

License

MIT License. See LICENSE.