donotreadagain 0.1.0__tar.gz

donotreadagain-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Something didn't work as expected
+labels: bug
+---
+
+**What happened**
+A clear description of the bug.
+
+**To reproduce**
+Exact `dnr` command(s) and, if possible, a minimal file/folder that triggers it.
+
+```
+$ dnr ...
+```
+
+**Expected**
+What you expected instead.
+
+**Environment**
+- dnr version (`dnr --version`):
+- Python version (`python --version`):
+- OS:
+- File type involved (PDF / PNG / JPEG / MP3 / docx / …):
+
+**Notes**
+Anything else — e.g. is the transcript flagged low-quality by `dnr status`? Is it in-file or db-only?

donotreadagain-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea or improvement
+labels: enhancement
+---
+
+**The problem / use case**
+What are you trying to do that's hard or impossible today?
+
+**Proposed solution**
+What you'd like to see (a flag, a command, a carrier, a behavior).
+
+**Fit with dnr's principles**
+dnr is a *deterministic substrate* — it doesn't infer metadata or do semantic/fuzzy work (that's the
+agent's job), owns no model, and keeps the file as the source of truth. Does your idea fit, or is it a
+conscious exception? (See [qna.md](../qna.md) for decisions already settled.)
+
+**Alternatives considered**
+Anything you tried or ruled out.

donotreadagain-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## What & why
+
+Briefly: what does this change, and why?
+
+## Checklist
+
+- [ ] Tests added/updated and `pytest` is green locally
+- [ ] No new hard model dependency in the core (dnr owns no model)
+- [ ] If a new carrier: `content_hash` is invariant under embed + re-embed is byte-stable (round-trip test added)
+- [ ] If agent-facing behavior changed: regenerated `SKILL.md` (`dnr skill > SKILL.md`)
+- [ ] Doesn't make dnr *infer* metadata (dates/parties/topics) or do fuzzy/semantic search — that stays the agent's job
+- [ ] Docs updated if needed (README / spec / qna)
+
+## Notes
+
+Link any relevant `qna.md` decision or spec section. Call out anything that rubs against a design principle.

donotreadagain-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Test
+        run: pytest -q
+      - name: Spec ⇄ schema in sync
+        run: |
+          python -c "import json,sys; from dnr import schema; \
+            cur=json.load(open('spec/dnr.schema.json')); \
+            sys.exit(0 if cur==schema.SCHEMA else 'spec/dnr.schema.json is stale — regenerate from dnr.schema.SCHEMA')"

donotreadagain-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# uv
+uv.lock.*
+.uv/
+
+# dnr index — regenerable cache (safe to ignore; can travel as a warm cache if desired)
+.dnr.db
+.dnr.db-wal
+.dnr.db-shm
+*.dnr.json
+
+# editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# scratch / experiments (local only, never committed)
+*.tmp
+/scratch/
+/experiments/

donotreadagain-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); this project uses [SemVer](https://semver.org/).
+
+## [Unreleased] — 0.1.0
+
+First public cut. Pre-release.
+
+### Added
+- **Read-once cache.** `dnr ingest` / `dnr record` transcribe a file once, sign the record (Ed25519),
+  and embed it in the file's own metadata; `dnr read` returns the verified transcript instead of re-parsing.
+- **Per-format `content_hash`** over *decoded* content (PDF streams, audio frames, decoded pixels, OOXML
+  manifest, NFC text), invariant under embedding — the identity + re-transcribe trigger.
+- **In-file carriers:** PDF (XMP), MP3 (ID3), PNG (iTXt), JPEG (APP segment). Pixels/content untouched.
+- **db-only records** in a per-folder `.dnr.db` for slotless formats (docx, …) and `--no-embed`
+  (evidentiary originals, byte-identical). Already-readable text gets no record. **No sidecar files.**
+- **Per-folder index** (SQLite + FTS5 trigram, Korean/CJK ok): `dnr index` + `dnr query` with composed
+  filters (`--match` ∩ `--tag` ∩ `--since/--until` ∩ `--where`), `--any` OR sweeps, `--dedup`,
+  `--min-chars`, `--context` KWIC, `--format json`.
+- **Query memory:** saved queries (`--save`/`dnr queries`/`--use`, re-run live), `dnr tag` and `dnr date`
+  for explicit (never-inferred) metadata.
+- **Self-describing distribution:** each record carries an `_about` pointer, the `.dnr.db` self-describes,
+  and agents fetch the skill once (`dnr skill` / `SKILL.md`). `dnr init` just ensures a key.
+- **Trust + quality:** signature + content_hash gate on `read`/`index`/`verify`; a low-quality
+  (empty/mojibake) transcript heuristic flagged by `dnr status` (`trusted ≠ faithful`).
+- CLI: `keygen, ingest, record, read, verify, guide, types, status, date, index, query, queries, tag,
+  init, skill, strip, validate, schema`.
+- Spec (`spec/dnr-0.1.md`) + JSON Schema + golden vectors; threat model (`SECURITY.md`).
+
+### Known limits
+- Not yet on PyPI; a standalone binary (Python-less environments) is future work.
+- Adoption (agents *knowing* dnr) is the real lever, not the tool alone.
+- More in-file carriers (OOXML, audio containers, video) and pre-query auto-scan are planned.

donotreadagain-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Code of Conduct
+
+## Our pledge
+
+We want dnr to be a welcoming, harassment-free project for everyone, regardless of
+experience, identity, or background.
+
+## Our standards
+
+Examples of behavior that helps:
+
+- Being respectful and constructive in issues, PRs, and reviews.
+- Welcoming newcomers and questions.
+- Accepting feedback gracefully and assuming good faith.
+
+Examples of unacceptable behavior:
+
+- Harassment, insults, or derogatory comments.
+- Personal or political attacks.
+- Publishing others' private information without permission.
+
+## Scope
+
+This applies in all project spaces (issues, pull requests, discussions) and when an
+individual is representing the project in public spaces.
+
+## Enforcement
+
+Report unacceptable behavior to the maintainer at **melodysdreamj@gmail.com**. Reports
+will be reviewed and handled confidentially. Maintainers may remove, edit, or reject
+contributions and comments that violate this Code of Conduct.
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), v2.1.

donotreadagain-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing to dnr
+
+Thanks for your interest! dnr is a small, principled codebase — a quick read of the principles below will save you (and a reviewer) time.
+
+## Getting started
+
+```bash
+git clone https://github.com/melodysdreamj/donotreadagain
+cd donotreadagain
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest                 # should be green in ~1s
+```
+
+Requires Python 3.10+. No API keys, no network, no services — the whole suite runs locally.
+
+## Project layout
+
+```
+src/dnr/
+  hashing.py     content_hash (per-format, over DECODED content) + whole_hash
+  record.py      build the record + RFC 8785 (JCS) canonicalization
+  signing.py     Ed25519 sign / verify; keyring.py manages the local key
+  embed.py       carriers — read/write the record into a file's slot (PDF/MP3/PNG/JPEG)
+  ingest.py      transcribe → record → sign → store; read_cached (the skip-reparse gate)
+  transcribe.py  local providers (pypdf, Whisper, python-docx) + quality/lang heuristics
+  index.py       per-folder .dnr.db (SQLite + FTS5): scan/harvest, query, query memory
+  guide.py       the verbatim transcription contract; skill.py / bootstrap.py: distribution
+  cli.py         the `dnr` command-line surface
+spec/            the normative spec + JSON Schema + golden vectors
+tests/           pytest; fast, hermetic
+SKILL.md         the agent skill (generated from skill.py via `dnr skill`)
+```
+
+## Design principles (please don't break these)
+
+1. **dnr is a deterministic substrate; the agent is the intelligence.** dnr does verifiable, repeatable primitives (hash, sign, full-text/structured query). It must **never *infer* metadata** (dates, case numbers, parties, topics) or do fuzzy/semantic search — that's the calling agent's job. Metadata is set *explicitly* (`dnr tag`, `dnr date`).
+2. **dnr owns no model.** The transcript is an *input*, produced by the agent (vision), a local model (Whisper, text-extract), or an API. Don't add a hard model dependency to the core.
+3. **File = canonical truth; the index is a regenerable cache.** Anything in `.dnr.db` (except authoritative db-only records) must be reconstructable from the files.
+4. **Determinism is load-bearing.** `content_hash` must stay invariant when the record is embedded, and re-embedding identical content must be byte-stable. New carriers must preserve this (see below). No timestamps in records/embeds.
+5. **`trusted ≠ faithful`.** Signing proves provenance + file-match, not transcription accuracy. Don't conflate them; surface quality, don't fake it.
+6. **No sidecar files, no per-folder notes.** Records live in-file or db-only; discovery rides on the artifacts' self-description.
+
+If a change rubs against one of these, say so in the PR — sometimes the principle should evolve, but it should be a conscious decision (see [qna.md](qna.md) for ones already settled).
+
+## Adding a format carrier (common contribution)
+
+To make a new format embed *in-file* (instead of db-only):
+
+1. Add `embed_<fmt>` / `extract_<fmt>` / `strip_<fmt>` in `embed.py`, register them in `_EMBED`/`_EXTRACT`/`_STRIP`.
+2. **Critical:** embedding must NOT change the file's *decoded content* — `hashing.content_hash` must be invariant before/after embed (e.g. for JPEG, insert a metadata segment without re-encoding the pixels). Re-embedding identical input must be byte-stable.
+3. Update `formats.py` (`SUPPORTED`) and add a test asserting: round-trip, `content_hash` invariance, idempotent re-embed, and `strip`.
+
+## Tests
+
+- Every change needs a test. The suite is the contract — keep it green and fast (no network, no large fixtures).
+- Use `tmp_path` and set `DNR_HOME` to an isolated dir (see the fixtures in `tests/`).
+- Run `pytest` before opening a PR.
+
+## Pull requests
+
+- Branch from `main`; keep PRs focused.
+- Conventional-ish commit subjects: `feat(dnr): …`, `fix(dnr): …`, `test: …`, `docs: …`.
+- If you changed agent-facing behavior, regenerate `SKILL.md` (`dnr skill > SKILL.md`) and update it.
+- Describe *what* and *why*; link any relevant `qna.md` / spec section.
+
+## Reporting bugs / ideas
+
+Open an issue (templates provided). For anything security-sensitive, see [SECURITY.md](SECURITY.md) — don't file a public issue for vulnerabilities.
+
+By contributing you agree your work is licensed under the project's [MIT License](LICENSE).

donotreadagain-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 june lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

donotreadagain-0.1.0/MILESTONES.md

@@ -0,0 +1,153 @@
+# dnr — Milestones
+
+Build roadmap. Full design → [vision.md](vision.md).   Status: ✅ done · 🔜 in progress / next · ⬜ todo
+
+**v0.1 goal —** a working `dnr` that ingests PDF + audio (transcribe → canonical-hash → deterministic embed → sign), builds a per-folder queryable index (Korean/CJK search included), and lets an agent read/query with **no install**. Fundamentals-first: the `content_hash` and signing primitives are *proven* before the rest is layered on.
+
+**Critical path:** M1 → M2 → (M3 ∥ M4) → M5 → M6 → M7 → M8 → M9.   **v0.1 cut** = M1–M8 (build) + **M9 (dogfood — the real release-readiness gate)**.   **M10–M14** = operability, security, the standard, scale, release.
+
+**Progress (2026-06-20):** working `dnr` package + CLI — `hashing`/`record`(JCS)/`embed`(PDF·mp3·sidecar; gates 1·2·4)/`signing`(Ed25519+keyring); `transcribe` (transcriber-agnostic: local text-extract + agent path + Whisper provider) + `guide` (verbatim contract `dnr-verbatim-1`); `ingest`/`read_cached` (skip-reparse, idempotent); `index` (`.dnr.db` fixed table + FTS5 **trigram for CJK** + incremental scan + move resilience + tombstone). CLI: **keygen·ingest·record·read·verify·guide·types·index·query**. End-to-end (ingest→index→query→read) works with **zero API keys**; `dnr init` installs the agent skill (one-phrase bootstrap); **57 tests green.** **M1–M12 landed.** Then a **broad multi-user dogfood** (11 personas, each in an isolated folder) found 2 ship-blockers the targeted run missed — **both now fixed**: (1) the **index/query trusted UNSIGNED records** (security bypass — `read`/`verify` refused forged records but `query` surfaced them); `scan` now verifies signature + content_hash before harvesting. (2) **duplicate-content PRIMARY-KEY collision** silently dropped a file; rows are now keyed by **path**. Also added `query --list`, "no results"/CJK-short-term hints, and stripped-record removal from the index. **Then the 3 high dogfood items were fixed too:** non-PDF `ingest` (text → `method:none` sidecar, searchable; images/unknown → clean "use `dnr record`" errors, no pypdf crash); **CJK <3-char search** (LIKE substring fallback → 2-char Korean terms 계약/이혼/특허 now match); **spec `content_hash`** now documents the `<CS>`/`<IM>` framing + ships **golden vectors** (`spec/vectors/`, text + audio). **Then format coverage expanded:** **docx** (local python-docx text-extract), **images** (JPEG/PNG/TIFF/WEBP — pixel content_hash + agent `dnr record` + sidecar), and OOXML content_hash; cross-format search verified (docx + image in one folder). **Then a real-corpus dogfood** (the founder's `law-example` — 12 real Korean legal docs) found + fixed 4 more bugs: **macOS NFD paths** (now NFC-normalized in the index), **`start_date` as a real column** (`--where` now consistent with `--sort`), **language auto-detect** (`lang='ko'` now works for local ingest), and **filename-searchable FTS** (terms in the filename now match). Query surface also gained `--tag`, `--sort/--desc`, `--match --context N` (KWIC snippets), `--list`, and `record --tags`. (`#5` Korean-PDF word-spacing is inherent to CJK PDF text layers — not fixable from text; use the vision/`dnr record` path.) **76 tests green**, all 4 fixes verified on the real corpus. Then **sidecars were removed entirely** (`.dnr.json` gone): **images now embed in-file** (PNG iTXt / JPEG APP segment — pixels untouched, content_hash invariant, multi-segment chunking for >64KB), text/docx/etc. store a **db-only** record in `.dnr.db` (authoritative; preserved across re-scans), and `--no-embed` forces db-only for evidentiary originals (file byte-identical). Distribution also moved from a per-folder note to a **fetch-once `SKILL.md`** + each record's `_about` self-pointer. Then a **query-memory** layer landed: **composed queries** (`--match` ∩ `--tag a,b` ∩ `--since/--until` ∩ `--where`, one shot), **saved queries** (`--save`/`dnr queries`/`--use` — stores the *query*, re-runs live so it never goes stale), and **`dnr tag <file> <tag>…`** so an agent accumulates tags as it works (carrier files re-indexed immediately). Remaining debt: golden vectors / cross-tool, proper `dnr:` XMP namespace, more in-file carriers (OOXML for docx, audio containers, video), pre-query auto-scan, ingest lock. **Distribution decided: assume Python 3.10+ (pip/pipx/`uvx --from donotreadagain dnr`) — Python's stdlib `sqlite3` covers the read path, so one dependency does both; a standalone per-platform binary for Python-less environments is deferred post-1.0.** Verified: a clean venv `pip install .` yields a working standalone `dnr` (no source tree), sqlite included.
+
+---
+
+## ✅ M0 — Foundation validated
+> Prove the load-bearing assumption before building on it.
+- [x] Design doc (`vision.md`) — architecture, schema, hashing, trust, distribution
+- [x] Repo init (git, MIT, README, .gitignore)
+- [x] **make-or-break experiment** — `content_hash` invariant under embed + every re-save mode (PDF/WAV)
+- [x] Deterministic embed recipe found → conformance **gate 4**
+
+## 🔜 M1 — Canonicalization core + conformance harness
+> The single primitive everything rests on — *and* the test infra that makes "any tool agrees" real.
+- [x] `content_hash(pdf)` — decompressed content streams + image XObjects, page order
+- [~] `content_hash(audio)` done (mp3 frames + wav data chunk); remaining: `content_hash(image)` (decoded pixels), `content_hash(ooxml)` (member manifest)
+- [~] Canonical record serialization — SHA-256 + RFC 8785 JCS done; NFC text normalization remaining
+- [ ] **Conformance harness** — golden test vectors per format + a runnable suite, wired into **CI** (gates run every commit)
+- [ ] **Cross-tool / cross-version determinism** — same `content_hash` across pikepdf/qpdf versions (and a 2nd library), not just self-consistency
+- [ ] Follow-up validations: real **scanned** PDF (image-only), multi-MB payload, real **mp3**
+- **Done when:** two independent tools/versions agree on `content_hash` for a real corpus, with published vectors.
+
+## 🔜 M2 — Embed / extract engine (carriers)
+> Write & read the record in each format's native slot, safely.
+- [~] Write: **PDF (XMP) · mp3 (ID3 TXXX) · sidecar `.dnr.json`** done; remaining: proper `dnr:` namespace, JPEG/PNG/TIFF/MP4, Vorbis, OOXML
+- [x] **Deterministic embed** (`deterministic_id`, no auto-timestamps) — gate 4
+- [x] **Atomic write** (temp + fsync + rename) — never mutate the original in place
+- [x] Preserve native tags (gate 2) · read-back + verify `content_hash` (gate 1)
+- [ ] Sidecar fallback rules: no slot / over size limit / read-only / sensitive
+- **Done when:** all 4 conformance gates pass per carrier in CI.
+
+## 🔜 M3 — Signing & trust
+> Make a record trustworthy enough to justify skipping a re-read.
+- [x] `record_hash = sha256(JCS(record − sig))`, Ed25519 sign / verify
+- [~] Keygen + trust list done; persistent local keyring remaining
+- [ ] Verify → trust tiers: signed + trusted + hash-match → **skip-reparse**; else **search-only + fallback**
+- [ ] `transcript` always handled as untrusted data, never as instructions
+- **Done when:** forged / altered / untrusted-key records are correctly refused for skip-reparse.
+
+## 🔜 M4 — Transcription (ingest)
+> Turn a raw file into a faithful record, once. **dnr owns no model** — the transcript is supplied by the agent or a local provider.
+- [x] **Transcriber-agnostic ingest pipeline** — content_hash → transcribe → record → sign → embed
+- [x] **Local `text-extract`** (pypdf, born-digital PDF, NFC) · **agent-supplied** path (`dnr record`) · **text files** (.txt/.md/.json/… → `method:none` sidecar) · clean errors for images/unknown
+- [ ] Local models: **Whisper** (audio) · local OCR/vision (scans); optional hosted API
+- [ ] Method hierarchy enforced: `text-extract` → `vision` → (`ocr` demoted)
+- [ ] **Verbatim** transcription contract (prompt) shipped in the skill: complete, no summary, mark uncertainty
+- [ ] provenance: version, instruction_id, prompt_hash, confidence; per-segment language tagging (feeds M6)
+- [ ] Cost control: query-driven lazy ingest · ask-the-user · `dnr ingest --glob --budget`
+- **Done when:** a PDF / audio ingests into a verbatim, signed, embedded record with provenance — agent-supplied or local, no API key required.
+
+## 🔜 M5 — Index (query layer)
+> A folder becomes a queryable table — cheaply, incrementally.
+- [x] `.dnr.db`: fixed base table + `dnr_fts` (FTS5) + `_dnr_readme`
+- [x] Incremental scan: stat → record → harvest; tombstone deletes
+- [~] **index ≠ ingest** done; cold-folder media → currently *skipped* (pending-rows TODO)
+- [ ] Pre-query incremental scan (`--no-scan` to skip)
+- [x] Move resilience: `content_hash` match → update `path` only
+- [~] Concurrency: SQLite **WAL** on; `content_hash` ingest lock TODO
+- **Done when:** second scan is fast (stat-skips ✅), queries are fresh, moves don't re-transcribe ✅
+
+## 🔜 M6 — i18n & search quality
+> Make non-English — especially Korean/CJK — actually searchable (the founder's own corpus).
+- [x] **trigram FTS5** + **LIKE substring fallback for <3-char terms** → 2-char Korean (계약/이혼/특허) matches; **filename also searchable** (FTS over name)
+- [x] **NFC normalization end-to-end** — index stores NFC paths/names (fixes macOS NFD); text NFC-normalized
+- [x] **language auto-detect** (script heuristic) → `lang` set on local ingest; `--where lang='ko'` works
+- [~] Multilingual `fields` consistency / RTL / bidi remaining
+- **Done when:** ✅ Korean legal-doc search (incl. 2-char terms + filenames) returns correct hits — verified on the real `law-example` corpus
+
+## 🔜 M7 — CLI & distribution
+> One tool that ties it together, runnable anywhere.
+- [~] `dnr init·ingest·record·read·verify·keygen·guide·types·index·query` done; `seal·strip` TODO
+- [x] Protocol enforced in code (`dnr read/index/query` are real commands, not prose)
+- [ ] `uvx` package **+ single static binary** (per-platform releases) — dependency-free drop-in
+- **Done when:** `uvx dnr index <folder>` and `dnr query` work on a fresh machine, offline (minus transcription API).
+
+## 🔜 M8 — Agent integration (consumer)
+> Zero-install consumption by AI agents.
+- [x] **agent skill (`SKILL.md`)**: fixed schema + example queries + consumer contract + verbatim guide; a fetchable skill (frontmatter name/description), **not** a per-folder note
+- [x] **skill encodes the full decision flow** (A: one file → self-validating `dnr read` / B: folder → status→transcribe→index→query) and was **adversarially tested** — fresh agents given only the skill text + 6 scenarios; judged vs the canonical flow + a doc critic over 4 rounds (3→4→5 correct, **0 wrong throughout**), fixing real gaps (read=self-validating; `--sidecar` mutation; transcribe-as-a-step; bulk-only ask-gate) so the wording matches actual CLI behavior
+- [~] Consumer path documented (`dnr read`/`query`; raw `sqlite3` via `_dnr_readme`)
+- [x] **transcribe-first ask-flow** — `dnr status <folder>` reports coverage by cost (model = image/audio/video / parse = PDF·Office / cheap = text); the skill tells the agent to run it on the first folder-wide question and **offer to transcribe-first** when expensive files are un-transcribed (one-time pass → every later view is a cache hit). Verified on the real corpus: `status 자료/` → "0/441 transcribed, 92 model + 202 parse pending → transcribe-first recommended".
+- [x] **No per-folder note — self-describing + fetch-once skill** — every record carries an `_about` pointer (and the `.dnr.db` readme points to the skill), so an agent that meets a dnr artifact fetches `SKILL.md` **once** (committed at the repo root / `dnr skill`) and then knows dnr in every folder; nothing is written into the user's folders. `dnr init` now only ensures a signing key. Run with no install via `uvx --from donotreadagain dnr`.
+- **Done when:** an agent given only the skill queries a dnr folder and skips re-parsing correctly; `dnr init` bootstraps from a single user phrase.
+
+## 🔜 M9 — Agent scenario testing & dogfooding
+> Drive the whole thing with real agents across many scenarios — the bugs that specs & unit tests miss surface here, and feed M10–M12. This is the real release-readiness gate.
+- [x] **Scenario matrix**, run by agents: cache-hit, cross-file query, cold folder, move, freshness, incremental, CJK, + adversarial
+- [~] **Multi-harness**: exercised via the real `dnr` CLI by agents; actual Claude Code / Codex / Cursor runs are a broader TODO
+- [x] **Adversarial / edge**: forged-unsigned (refused), tampered-signed (verify fails), freshness (no stale leak), corrupt/garbage file
+- [x] **Measure**: 8/10 pass, security held, failure taxonomy + prioritized backlog produced
+- [x] Run as a **multi-agent workflow** (10 scenarios in parallel + synthesis)
+- **Done when:** ✅ matrix complete with a failure list; fixes fed back (corrupt-file robustness → done). Remaining low-pri: CJK <3-char FTS, file-embedded-cache note.
+
+## 🔜 M10 — Reversibility & corpus operability
+> Make it safe to undo, and runnable at corpus scale.
+- [x] **Robustness** (from M9 dogfooding): corrupt/missing files no longer crash — clean errors, one bad file never aborts a scan; `dnr read` falls back gracefully
+- [x] `dnr strip` (un-embed, in-file + sidecar; content unchanged) · **bulk rollback** TODO
+- [ ] **Resumable / idempotent** ingest after crash · `--dry-run`
+- [ ] Rebuild a corrupted/lost `.dnr.db` without re-incurring transcription
+- [ ] **Model-upgrade policy**: re-transcribe only lossy methods (asr/ocr/vision), skip `text-extract`; partial/lazy migration; mixed-version coherence
+- [ ] Backup/dedup awareness (embedding changes whole_hash → re-backup churn)
+- **Done when:** a bad bulk ingest is fully revertible and a crashed run resumes cleanly.
+
+## 🔜 M11 — Security & privacy
+> Treat every embedded record as untrusted input; don't leak on share.
+- [x] **Threat-model document** — `SECURITY.md` (injection, forgery, TOFU, exfiltration, custody) + dogfood evidence
+- [~] `transcript` as untrusted data (skill + contract); injection covered by forged/tampered dogfood; dedicated injection corpus TODO
+- [~] `dnr strip` before sharing done; sensitivity-flag refuse-embed TODO
+- [~] Poisoning surface documented; sanitization helpers TODO
+- **Done when:** ✅ dogfooding showed a malicious/forged/tampered file cannot pass as trusted or steer the agent.
+
+## 🔜 M12 — Spec formalization (the standard)  ← the goal
+> Make it implementable by others, and able to evolve.
+- [x] `spec/dnr-0.1.md` (normative) + `spec/dnr.schema.json` (JSON Schema) + `dnr validate` / `dnr schema`
+- [x] Carrier mapping table · per-format canonicalization (incl. documented PDF `<CS>`/`<IM>` framing) · conformance gates (in spec)
+- [x] **Golden conformance vectors** — `spec/vectors/` (text + audio) + a test the impl must reproduce; PDF/image/OOXML vectors pending
+- [~] Versioning / forward-compat in spec; profile registry, governance = TODO
+- **Done when:** a second, independent implementation passes the published vectors (text/audio shipped; PDF vector + a real 2nd impl remain).
+
+## 🔜 M13 — Format expansion & scale hardening
+- [~] **docx** (local extract) + **images** JPEG/PNG/TIFF/WEBP (pixel content_hash + sidecar + agent record) done; remaining: FLAC/OGG/M4A/MP4·MOV, xlsx/pptx, in-file image XMP/PNG-iTXt, local Whisper wired
+- [ ] Large-corpus performance · multi-agent stress · recovery primitives at scale
+
+## ⬜ M14 — Release, governance & adoption
+> Ship, then earn adoption with **proof** — not cold asks. (See "Adoption strategy" below.)
+- [ ] v0.1 public release on GitHub
+- [ ] **Benchmark** (the key adoption asset): measured token / latency savings on re-reads + agent protocol-compliance rate (built on M9's numbers)
+- [ ] 2-minute demo · one-command try (`uvx dnr …`)
+- [ ] **Launch posts** (GeekNews / Show HN) — lead with the demo + benchmark; CTA = the one-phrase bootstrap (`uvx dnr init`). A spike, not a strategy — only after v0.1 + the try-path are frictionless.
+- [ ] **Opt-in surfaces first**: MCP server + skill/`AGENTS.md` snippet (users adopt without any maintainer PR)
+- [ ] **OKF-compatible sidecar emit** (ride existing rails, don't fight them)
+- [ ] **Targeted integrations**: PRs only to projects with a clean plugin/tool extension point — benefit-first, after the benchmark exists
+- [ ] Governance: contribution process + spec change control
+- **Done when:** ≥1 external project/user adopts via the opt-in surface, with the benchmark as evidence.
+
+---
+
+### Adoption strategy (M14) — why "proof-then-pitch", not cold PRs
+1. **Prove first.** Maintainers adopt things that already work + have a number, not specs. Ship → benchmark (token/latency savings) → a few real users → *then* integrate.
+2. **Opt-in beats PR.** Consumption is ambient `sqlite3`, so the integration is tiny — and an **MCP server / skill snippet** lets users turn it on with zero maintainer change, sidestepping PR rejection. Reserve real PRs for projects with a plugin/tool registry.
+3. **Benefit-first messaging.** Not "adopt my standard" — "your agent re-parses PDFs every turn; drop this in for an N% saving." Show, don't tell.
+4. **Target narrowly.** Document-heavy RAG / coding / research agents where re-parsing is a felt pain. 50 drive-by PRs read as spam and cost reputation; a few working, wanted integrations win.
+
+---
+
+*All docs in English (public repo).*

donotreadagain-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: donotreadagain
+Version: 0.1.0
+Summary: Read once, never again — self-describing files so AI agents stop re-parsing.
+Project-URL: Homepage, https://github.com/melodysdreamj/donotreadagain
+Project-URL: Repository, https://github.com/melodysdreamj/donotreadagain
+Project-URL: Issues, https://github.com/melodysdreamj/donotreadagain/issues
+Author: june lee
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,cache,metadata,pdf,self-describing,transcript,xmp
+Requires-Python: >=3.10
+Requires-Dist: cryptography
+Requires-Dist: jsonschema
+Requires-Dist: mutagen
+Requires-Dist: pikepdf>=8
+Requires-Dist: pillow
+Requires-Dist: pypdf
+Requires-Dist: python-docx
+Requires-Dist: rfc8785
+Provides-Extra: dev
+Requires-Dist: fpdf2; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# donotreadagain (`dnr`)
+
+> **Read once, never again.** Embed a faithful, signed AI transcript into each expensive-to-parse file's own metadata, so AI agents stop re-OCR/re-parsing the same PDF, image, scan, or audio every time.
+
+[![tests](https://img.shields.io/badge/tests-passing-brightgreen)](#development) [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml) · **status:** v0.1, pre-release
+
+---
+
+## The problem
+
+AI agents re-parse the same file *every time they touch it* — re-OCR a scan, re-run vision on a screenshot, re-transcribe an audio clip, re-extract a PDF. It's slow, it burns tokens and model calls, and it's non-deterministic. In **repeat-access corpora** (legal, research, compliance) the same documents get read dozens of times; with **multi-agent** setups every agent re-parses independently. The waste compounds exactly where it hurts.
+
+## The idea
+
+dnr reads a file **once**, then writes a verbatim transcript + structured metadata **into the file's own native metadata slot** as a *signed* JSON record — the file becomes **self-describing**. Any agent that opens it later reads the cached transcript instead of re-parsing. A per-folder SQLite + FTS5 index makes a whole folder searchable without opening anything.
+
+The second view is the win:
+
+| | first view (re-parse) | second view (cached) |
+|---|---|---|
+| born-digital PDF | ~1.4 s (pypdf) | ~60 ms — **~22× faster** |
+| image / scan / audio | a vision / Whisper model call | a few ms of text — **no model at all** |
+
+…and the cache is **trustworthy**: a record is used only if it's signed by a trusted key *and* its `content_hash` still matches the file, so "fast" never means "stale or forged."
+
+## Demo
+
+```console
+$ dnr ingest contract.pdf            # transcribe once → sign → embed in the file
+ingested contract.pdf  [in-file]
+  method=text-extract transcriber=pypdf
+  signed key_id=ce6d170a497238f7
+
+$ dnr read contract.pdf              # later (or from any agent): verified cache hit — no re-parsing
+LOAN AGREEMENT
+Lender: Acme Capital LLC
+Borrower: Jordan Smith
+Principal: USD 1,200,000
+...
+
+$ dnr index ./contracts
+$ dnr query ./contracts --match damages --context 40    # search a whole folder, no files opened
+contract.pdf
+    … Principal: USD 1,200,000  Maturity: 2026-12-31  Damages clause: section 7.
+```
+
+The transcript lives *inside* `contract.pdf` — move it, email it, hand it to another agent, and the cached transcript travels with it.
+
+## Quickstart
+
+Requires **Python 3.10+** (its stdlib includes the `sqlite3` used to read the index — one dependency covers both).
+
+```bash
+# run with no persistent install:
+uvx --from donotreadagain dnr <cmd>
+# or install:
+pipx install donotreadagain        # or: pip install donotreadagain
+```
+
+```bash
+dnr ingest report.pdf              # transcribe once (local) → sign → embed in the file
+dnr read   report.pdf              # print the cached transcript (verified), or fall back
+dnr index  ./case-folder           # build .dnr.db
+dnr query  ./case-folder --match "손해배상" --tag 가압류 --since 2025-01-01
+```
+
+For a scan / image / anything you must *look* at, the agent transcribes it and records the result:
+
+```bash
+dnr record scan.png --transcript-file t.md --method vision --transcriber <your-model>
+```
+
+## How it fits together
+
+```
+File = canonical truth                    Index .dnr.db = derived, regenerable
+┌────────────────────────────┐  harvest  ┌────────────────────────────┐
+│  signed dnr record          │ ───────▶  │  fixed table + FTS5 search  │
+│  content_hash · transcript  │           │  path · tags · transcript … │
+│  provenance · fields · sig  │           └────────────────────────────┘
+└────────────────────────────┘                 ▲ query via sqlite3 — no dnr install needed
+   ▲ transcribe · sign · embed once (expensive)
+```
+
+**Where the record lives (no sidecar files):**
+- **In-file** for formats with a metadata slot — PDF→XMP, MP3→ID3, PNG→iTXt, JPEG→APP segment. Pixels/bytes-of-content untouched (`content_hash` invariant), so the transcript **travels with the file** (move it, email it — it's still there).
+- **db-only** in the folder's `.dnr.db` for formats with no slot yet (docx, …), or via `--no-embed` for evidentiary originals you must not modify (file left byte-identical).
+- **Nothing** for already-readable text (`.txt`/`.md`/`.csv`) — an agent just reads it.
+
+## Using it
+
+- **Read (consumer):** `dnr read <file>` returns the cached transcript only if it's present, trusted, and still matches (self-validating — a changed file silently misses). No dnr tool? An agent can read `.dnr.db` directly with ambient `sqlite3` (the db's `_dnr_readme` table self-describes).
+- **Transcribe (producer):** `dnr ingest` (local: pypdf / Whisper / python-docx) or `dnr record` (agent supplies a vision transcript). dnr **owns no model** — the transcript is an input from whoever's best placed.
+- **Query a folder:** `dnr query <folder>` combines `--match` (FTS, Korean/CJK ok) ∩ `--tag a,b` ∩ `--since/--until` ∩ `--where`; plus `--any` (OR sweep), `--dedup`, `--context` (KWIC), `--format json`. Save composed queries with `--save`/`--use`; accumulate labels with `dnr tag`.
+- **Agents onboard once:** point an agent at a dnr folder and it fetches **[SKILL.md](SKILL.md)** once — then it knows dnr everywhere. `dnr init` just ensures a signing key; nothing is written into your folders.
+
+## Design principles
+
+- **dnr is the deterministic substrate; the agent is the intelligence.** dnr does verifiable primitives (hash, sign, full-text/structured query); it never *infers* metadata (dates, parties, topics) or does fuzzy semantic search — that's the agent's job. Set metadata explicitly with `dnr tag` / `dnr date`.
+- **File = truth, index = regenerable cache.** Delete `.dnr.db` and rebuild it from the files anytime.
+- **Transcriber-agnostic.** dnr ships a *contract* (the verbatim guide) + a *trust layer*, not a model. Fidelity is the transcriber's; provenance is recorded so a consumer can apply its own quality policy (`trusted ≠ faithful`).
+
+## Status & honest limits
+
+v0.1, pre-release. Works today for repeat-access corpora; validated by real-corpus dogfooding. Known limits we're explicit about:
+- **Adoption is the real lever.** The value compounds when agents *know* dnr (a skill, eventually native support) — not from the tool alone.
+- **`trusted ≠ faithful`.** A signature proves *who made it + that it matches the file*, not that the transcription is accurate. Low-quality/garbled transcripts are flagged (`dnr status`), not silently trusted.
+- **Not yet published** to PyPI; a standalone binary for Python-less environments is future work.
+
+See **[vision.md](vision.md)** (design) · **[spec/dnr-0.1.md](spec/dnr-0.1.md)** (spec) · **[SECURITY.md](SECURITY.md)** (threat model) · **[qna.md](qna.md)** (settled design decisions) · **[MILESTONES.md](MILESTONES.md)** (roadmap).
+
+## Development
+
+```bash
+git clone https://github.com/melodysdreamj/donotreadagain
+cd donotreadagain
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest                       # the suite is green and fast
+```
+
+Contributions welcome — see **[CONTRIBUTING.md](CONTRIBUTING.md)**.
+
+## License
+
+[MIT](LICENSE) © 2026 june lee