dicom-dre 1.0.0.dev7__tar.gz → 1.0.0.dev8__tar.gz

{dicom_dre-1.0.0.dev7 → dicom_dre-1.0.0.dev8}/.github/copilot-instructions.md

@@ -26,6 +26,7 @@ INTERACTION & REASONING GUIDELINES
   Never use marketing terms (efficient, compelling, comprehensively, effectively, successfully).
   Never use promotional adjectives (comprehensive, robust, powerful, optimized, seamless, flexible, scalable, intuitive, advanced, cutting-edge).
   Never use enthusiastic phrases (Perfect! Excellent! Great! Awesome! I have successfully...).
+  Avoid the informal term "knobs" for configurable values; use "settings", "options", or "parameters".
   Avoid evaluative or subjective judgments.
   Prefer verbs and concrete nouns over adjectives.
   Omit unverifiable or unquantifiable claims.
@@ -105,6 +106,26 @@ DOCSTRINGS & COMMENTS
 - First line: short summary sentence
 - Document all public classes, methods, and functions
 - Never write obvious comments that simply restate what the code does
+- Omit self-evident or trivially true statements. Do not document facts the
+  reader can infer from the signature, types, or an obvious guarantee (for
+  example "this module has no dependencies so it avoids an import cycle",
+  "returns a value", "this is a helper"). Record a fact only when it is
+  non-obvious and affects correctness, safety, performance, or correct use.
+- State what the code does, not what it does not do. Avoid negative-space
+  statements that contrast with an alternative or a prior design (for example
+  "not passed to X", "rather than closing over Y"); these are usually
+  refactoring artifacts. Keep a negative statement only when it conveys
+  critical information the reader cannot infer, such as a safety constraint.
+- Write dry, precise prose using established computer science and engineering
+  terms. Name the actual mechanism, not an analogy for it.
+- Do not use metaphor or anthropomorphism. Data does not "travel", "live",
+  "ship", "flow", or get "baked in"; objects do not "carry", "own", or "want".
+  Use precise verbs instead: "is stored in", "resides in", "is fixed at
+  construction", "is serialized to", "is passed to", "occurs", "is scoped to".
+- Prohibited terms and replacements: "baked" -> "fixed"/"set at construction";
+  "knobs" -> "settings"/"options"/"parameters"; "lives" -> "is stored"/
+  "resides"/"occurs"; "travel"/"ship" -> "is serialized"/"is sent"/"is passed";
+  "carries" -> "holds"/"contains".
 
 Example:
 def add(x: int, y: int) -> int:

dicom_dre-1.0.0.dev8/.github/instructions/docs.instructions.md

@@ -0,0 +1,84 @@
+---
+description: Writing documentation in docs/
+applyTo: "docs/**/*.md, README.md"
+---
+
+# Writing Documentation in dicom-dre
+
+Rules for writing and editing Markdown documentation under `docs/`. Favor the
+reader: a clear page is more likely to be correct, cheaper to change, and safe
+to reuse. Clarity is the primary goal; the rules below serve it.
+
+## Voice and Style
+
+- Write as dry as an IEEE or NIST specification: factual, declarative, and
+  impersonal. State facts and requirements; omit motivation, praise, and asides.
+- Use present tense and the active voice ("The engine hashes the value", not
+  "The value is hashed by the engine").
+- Prefer verbs and concrete nouns over adjectives.
+- Omit marketing and promotional words (for example efficient, powerful, robust,
+  seamless, comprehensive, advanced).
+- Omit claims you cannot verify from the code or tests.
+
+## What to Include
+
+- State what a component does, not what it does not do. Avoid negative-space
+  descriptions that contrast with an alternative or a prior design (for example
+  "handled here rather than in the parent", "not passed to X"); these are
+  usually refactoring artifacts. Keep a negative statement only when it conveys
+  critical information the reader cannot infer, such as a safety constraint.
+- Omit self-evident or trivially true statements. Do not state facts the reader
+  can infer or that hold by construction (for example "this module has no
+  dependencies so it avoids an import cycle"). Write only what is non-obvious
+  and consequential.
+
+## Terminology and Verbs
+
+- Name the actual mechanism, not an analogy. Do not use metaphor or
+  anthropomorphism: data does not "travel", "live", "ship", "flow", or get
+  "baked in"; objects do not "carry", "own", "want", or "know" anything.
+- Use precise verbs for the operation:
+  - storage or location: "is stored in", "is held in", "resides in".
+  - fixed at construction: "is fixed at construction", "is set once at
+    construction time".
+  - cross-process transfer: "is serialized to", "is pickled and sent to", "is
+    passed to". State that it crosses the process boundary when relevant.
+  - occurrence or scope: "occurs", "is performed", "is scoped to".
+- Prefer terms of art already used in the codebase: serialization,
+  immutability, process boundary, construction time, apply time, deterministic
+  derivation, closure.
+- Prohibited terms and replacements: "baked" -> "fixed"/"set at construction";
+  "knobs" -> "settings"/"options"/"parameters"; "lives" -> "is stored"/
+  "resides"/"occurs"; "travel"/"ship" -> "is serialized"/"is sent"/"is passed";
+  "carries" -> "holds"/"contains".
+
+## Punctuation
+
+- Do not use em-dashes (`--` or the Unicode em-dash). Rephrase into separate
+  sentences, or use a colon, comma, or parentheses.
+- Do not use en-dashes for ranges in prose. Write "10 to 30", not "10-30".
+
+## Conciseness
+
+- Keep sentences short. Prefer several plain sentences over one long clause.
+- Cut filler and hedging (for example "in order to", "it is important to note
+  that", "basically", "simply").
+- Make each point once. One idea per sentence; one topic per paragraph.
+
+## Formatting
+
+- Wrap prose at roughly 88 columns to match the source line length.
+- Wrap element names, keywords, parameters, and file paths in backticks
+  (`PatientID`, `HASH_SALT`, `~/.config/dicom-dre/salt`).
+- Use fenced code blocks with a language hint for commands and code.
+- Use relative Markdown links between docs pages
+  (`[Reproducibility](reproducibility.md)`).
+- Do not use emoji.
+
+## Accuracy
+
+- Keep documentation synchronized with the code. When behavior changes, update
+  the affected pages in the same change.
+- Verify CLI flags, parameter names, and defaults against the actual source and
+  `--help` output before documenting them.
+- When adding a new page, add it to the `nav`/`toctree` so it is reachable.

dicom_dre-1.0.0.dev8/.github/skills/pr-template/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: pr-template
+description: 'Generate GitHub-flavored markdown for a pull request against the development branch, formatted as conventional-commit release notes for reuse as a squash/merge commit body. Use when writing a PR description, drafting release notes, or preparing a commit message body.'
+argument-hint: 'against development; optional JIRA ticket'
+---
+
+# Skill Instructions
+
+This skill generates a pull request description in GitHub-flavored markdown format
+for the current branch against the development branch. The description is written as
+conventional-commit release notes so it can be reused directly as the body of a
+squash/merge commit that feeds python-semantic-release.
+
+## When to Use
+
+- Writing a pull request description for a branch targeting `development`
+- Drafting release notes for a set of branch commits
+- Preparing a squash/merge commit message body in conventional-commit format
+
+## Output
+
+The skill produces a markdown template containing:
+- A conventional commit header line (`<type>[scope]: <description> (STAR-12345)`)
+- A short summary paragraph
+- Change groups organized by conventional commit type (Features, Bug Fixes,
+  Performance, Refactoring, Documentation, Tests), each as a bullet list
+- An `### Interface and behavior changes` section when the branch changes existing
+  behavior or removes a public interface
+
+The output is formatted in a code block for easy copy/paste into GitHub and into a
+commit message.
+
+## Execution Steps
+
+Large branches produce diff output that exceeds the terminal capture limit and gets
+truncated. Gather change data with compact, aggregated commands first, then read
+individual files or scoped diffs only when needed. Do not pipe these commands through
+`head`/`tail`; that hides data rather than fixing truncation. Run each command
+separately so one large result does not push another out of view.
+
+### Step 1: Gather Branch Information
+
+Get the current branch name:
+```bash
+git branch --show-current
+```
+
+Get commits not in development (short and complete; count first if it may be long):
+```bash
+git rev-list --count development..HEAD
+git log --oneline development..HEAD
+```
+
+Get a per-directory change summary that stays small on large branches:
+```bash
+git diff development...HEAD --name-status | awk '{n=$1; $1=""; path=$0; sub(/^ /,"",path); d=path; sub(/\/[^\/]*$/,"",d); print n, d}' | sort | uniq -c | sort -rn
+```
+
+Get file-level status without the size graph (avoids per-line path truncation):
+```bash
+git diff development...HEAD --name-status
+```
+
+Use `--stat=200,200` only when line counts are needed; the wide format prevents path
+and bar truncation:
+```bash
+git diff development...HEAD --stat=200,200
+```
+
+### Step 2: Analyze Changes
+
+Work from the aggregated summaries in Step 1 to identify the change groups on the
+branch. When a specific area needs detail, read the file directly or take a diff scoped
+to one path rather than dumping the whole diff:
+```bash
+git diff development...HEAD -- <path>
+```
+
+Map each change to a conventional commit type:
+- `feat` -> Features
+- `fix` -> Bug Fixes
+- `perf` -> Performance
+- `refactor` -> Refactoring
+- `docs` -> Documentation
+- `test` -> Tests
+- `chore` / `build` / `ci` -> Maintenance (only when relevant)
+
+Summarize the branch by its net effect relative to `development`, not by its individual
+commits. A `fix` commit only belongs under Bug Fixes when it corrects behavior that
+already exists on `development` (a prior release). A commit that fixes code introduced
+earlier in this same branch is part of building that feature, not a bug fix against a
+release: fold it into the relevant Features bullet or omit it. To decide, check whether
+the fixed code path exists on `development`:
+```bash
+git log --oneline development..HEAD -- <path>
+```
+If every commit touching that path is on this branch (nothing on `development`), treat
+the change as feature development, not a Bug Fix.
+
+Identify any change that alters existing behavior, removes a public interface, or
+changes default output. List these under the interface and behavior changes section.
+A change is only an interface or behavior change when it affects code that exists on
+`development`; interfaces added and then adjusted within this branch are new, not changed.
+
+### Step 3: Identify JIRA Ticket
+
+Extract the JIRA ticket number from the branch name or commits (e.g., STAR-12345).
+
+### Step 4: Generate Release Notes
+
+Write the description as conventional-commit release notes.
+
+#### Header
+Single conventional commit header line:
+- `feat: add capability (STAR-12345)`
+- `fix: resolve issue (STAR-12345)`
+- `feat: replace ctp CLI with anonymize CLI (STAR-12345)`
+- `refactor: move result models (STAR-12345)`
+
+Use the type of the dominant change on the branch. If several types are present,
+choose the highest-impact type (`feat` > `fix` > others).
+
+#### Summary
+One short paragraph (two to four sentences) describing what the branch does and why.
+Keep it in present tense.
+
+#### Change Groups
+Add one `###` section per conventional commit type that applies, in this order:
+Features, Bug Fixes, Performance, Refactoring, Documentation, Tests. Under each,
+list changes as bullet points. Use a bold `**scope**:` lead-in where a scope
+clarifies the entry. Omit any section that has no entries.
+
+Before writing the Bug Fixes section, apply this gate to every candidate fix:
+1. Identify the files the fix touches.
+2. Run `git log --oneline development..HEAD -- <path>` and check whether the code being
+   fixed already existed on `development`.
+3. If the code path is net-new on this branch (all of its history is on the branch),
+   the fix is part of building the feature. Do NOT list it under Bug Fixes; fold its
+   substance into the matching Features bullet or drop it.
+4. Only keep a bullet under Bug Fixes when it corrects behavior that shipped on
+   `development` in a prior release.
+
+On a feature branch this usually leaves Bug Fixes empty. That is expected; omit the
+section entirely rather than repurposing it for intra-branch corrections.
+
+#### Interface and behavior changes
+When the branch changes existing behavior or removes a public interface, add a
+`### Interface and behavior changes` section with one bullet per change. Do not add a
+footer token.
+
+#### CTP script and native anonymizer changes
+Do not compress CTP script or native anonymizer edits into a single dense bullet. Give
+each its own section and show the actual code so the reader can see exactly what changed.
+
+- Changes to CTP scripts (`resources/dicom/scripts/**/*.xml`) go under a
+  `### CTP script changes` section. Show the affected rule text in an `xml` fenced code
+  block, then describe each element's old -> new effect as bullets keyed by tag.
+- Changes to the native (dicom-dre) engine adapter or profile policy
+  (`core/dre_engine.py`, `core/deid_profile.py`) go under a `### Native anonymizer changes`
+  section. Show the relevant Python in a `python` fenced code block, then describe what
+  each entry changes. (Catalog, tag, and action changes now live in the external
+  `dicom-dre` package, not this repository.)
+
+Gather the exact lines with scoped diffs, and render the resulting rule/catalog text in
+the code block rather than the raw `+/-` diff:
+```bash
+git diff development...HEAD -- src/starr_imaging/resources/dicom/scripts
+git diff development...HEAD -- src/starr_imaging/core/dre_engine.py src/starr_imaging/core/deid_profile.py
+```
+Show only the elements that changed, one code block per script family or catalog area,
+with the prose description immediately beneath the block.
+
+In each of these sections, also list the tests and regression-flow changes introduced
+for the rule change, so the validation lives next to the rule it covers. Find them with
+scoped diffs and name the specific test or flow behavior:
+```bash
+git diff development...HEAD --name-status -- tests
+git diff development...HEAD -- src/starr_imaging/flows/regression
+```
+For example, note a new cross-reference test asserting a tag's action, a regression
+comparison that now checks the tag, or a regression-flow change that exercises the rule.
+When the same tests are already summarized under the Tests section, reference them here
+rather than duplicating the full list.
+
+### Step 5: Format Output
+
+Wrap the entire template in a markdown code block so it copies cleanly into both the
+GitHub PR field and a commit message:
+
+````markdown
+```markdown
+feat: <short description> (STAR-12345)
+
+<one short summary paragraph>
+
+### Features
+- **scope**: change description
+- change description
+
+### Bug Fixes
+- change description
+
+### Documentation
+- change description
+
+### Tests
+- change description
+
+### Interface and behavior changes
+- change description
+
+### CTP script changes
+```xml
+<rule text that changed>
+```
+- (gggg,eeee) TagName: old -> new, and the effect on output
+- Coverage: test or regression-flow change that validates this rule
+
+### Native anonymizer changes
+```python
+# catalog / profile / action code that changed
+```
+- description of what this entry changes
+- Coverage: test or regression-flow change that validates this rule
+```
+````
+
+## Example Output
+
+For a branch that adds a native de-identification engine and replaces a CLI:
+
+````markdown
+```markdown
+feat: add native Python de-identification engine and no-deid profile (STAR-11973)
+
+Adds a native Python DICOM de-identification engine that runs alongside the existing
+CTP engine, selected per run via a new `deid_engine` setting that defaults to `ctp`.
+A native engine removes the runtime dependency on the CTP Java process, gives direct
+control over the anonymization pipeline, and enables device-specific private-tag
+handling. Regression runs both engines end-to-end and compares native output against
+CTP tag-by-tag.
+
+### Features
+- **anonymizer**: add native engine with rule catalog, tag definitions, profiles
+  (default, lds, lds-no-dob, pre-scrub), pixel blanker, and JPEG DCT annotation removal
+- **settings**: add `deid_engine` setting (`STARR_IMAGING__DEID_ENGINE`), defaulting to `ctp`
+- **processor/flows**: add per-run engine-selection parameter to the DICOM processor
+  and Stetson flows
+- **profiles**: add `no-deid` pass-through profile that emits source DICOM unchanged;
+  engine-independent and byte-identical across `ctp` and `native`
+- **robustness**: enable `convert_wrong_length_to_UN` and tolerate `BytesLengthException`
+  so malformed vendor private elements are preserved as `UN`
+
+### Documentation
+- add native anonymizer, de-identification, device catalog, and JPEG DCT anonymizer docs
+
+### Tests
+- add unit tests for catalog, profiles, pixel blanker, JPEG DCT anonymizer, per-engine
+  worker selection, and no-deid pass-through
+- add integration test asserting `no-deid` output is byte-identical to source on both engines
+
+### Interface and behavior changes
+- **CLI**: remove the `ctp` CLI in favor of the new `anonymize` CLI
+- **models**: move `AnonymizerResult` and outcome models to `core/models/anonymizer_models.py`;
+  replace `AnonymizedOutcome.was_scrubbed: bool` with `scrub_regions: frozenset[ScrubRegion]`
+
+### CTP script changes
+The metadata scripts (`resources/dicom/scripts/metadata.xml` and the `lds/` and
+`lds-no-dob/` variants) change to reach parity with the native engine:
+
+```xml
+<e t="00120063" n="DeIdentificationMethod">@always()</e>
+<e t="00180015" n="BodyPartExamined">@keep()</e>
+<e t="00540016" n="RadiopharmaceuticalInformationSequence">@process()</e>
+<e t="30060008" n="StructureSetDate">@incrementdate(this,@JITTER)</e>
+```
+
+- (0012,0063) DeIdentificationMethod: add `@always()` so the tag is written even when
+  the source omits it.
+- (0018,0015) BodyPartExamined: `@require()` -> `@keep()`, retaining the original value.
+- (0054,0016) RadiopharmaceuticalInformationSequence: drop `@always()`; the sequence is
+  processed in place.
+- (3006,0008) StructureSetDate: `@incrementdate(this,@DATEINC)` ->
+  `@incrementdate(this,@JITTER)`, fixing an undefined parameter so RTSTRUCT dates jitter
+  consistently.
+- Coverage: the CTP cross-reference test asserts these four tag actions, and the
+  regression engine comparison now includes (3006,0008) so CTP and native output match.
+
+### Native anonymizer changes
+The native catalog encodes the same rules as the CTP scripts so both engines agree:
+
+```python
+TagRule(Tag(0x0012, 0x0063), Action.ALWAYS),   # DeIdentificationMethod
+TagRule(Tag(0x0018, 0x0015), Action.KEEP),      # BodyPartExamined
+TagRule(Tag(0x0054, 0x0016), Action.PROCESS),   # RadiopharmaceuticalInformationSequence
+TagRule(Tag(0x3006, 0x0008), Action.JITTER_DATE),  # StructureSetDate
+```
+
+- Each rule mirrors the CTP element above; regression compares the resulting output
+  tag-by-tag to confirm the two engines match.
+- Coverage: the catalog unit test asserts each `TagRule` action, and the regression
+  flow runs both engines end-to-end and diffs these tags.
+```
+````
+
+This branch is a pure feature addition, so there is no Bug Fixes section. Intra-branch
+corrections to the new native engine (for example, fixing the pixel blanker no-op path,
+making `=` matching case-insensitive, or regenerating `file_meta` to avoid PHI leakage)
+are part of building the native engine and are represented by the native-engine Features
+bullet, not listed as Bug Fixes. The CLI and model changes touch code that exists on
+`development`, so they appear under Interface and behavior changes. The CTP script and
+native catalog edits get their own sections with the actual rule text shown as code
+blocks, rather than a single dense bullet.
+
+## Tips
+
+- Keep the summary paragraph short; put detail in the grouped bullet lists
+- Use present tense ("adds feature" not "added feature")
+- Group every change under the matching conventional commit type; omit empty groups
+- Give CTP script changes and native anonymizer profile/catalog changes their own
+  sections with the actual rule or catalog code in fenced code blocks and a per-item
+  description; never compress them into one dense bullet, and list the tests or
+  regression-flow changes that validate each rule alongside it
+- Summarize net effect vs. `development`, not per-commit history. Fixes to code that was
+  introduced earlier on this same branch are feature development, not Bug Fixes; fold
+  them into the Features bullet or drop them. Reserve Bug Fixes for corrections to
+  behavior that shipped in a prior release.
+- Small commits with generic messages (e.g., "fix typo", "wip", "cleanup", "address
+  review", "copilot feedback", "code review suggestions", formatting-only changes) can
+  be excluded from the summary; roll them up or omit them rather than adding a bullet
+  per commit
+- Only include the `### Interface and behavior changes` section when the branch actually
+  changes existing behavior or removes a public interface
+- Follow conventional commits format for the header
+- Extract JIRA ticket numbers from branch names (e.g., feat/STAR-12345-description)
+
+## Notes
+
+- Always compare against the `development` branch, not `main`
+- Use three-dot diff notation (`development...HEAD`) to see changes
+- The output should be ready to paste directly into a GitHub PR description and reused
+  as a squash/merge commit body
+- The header type determines the version bump python-semantic-release applies
+  (`feat` -> minor, `fix`/`perf` -> patch). Do not add a footer token.
+- Markdown code blocks make it easy to copy/paste without formatting issues

{dicom_dre-1.0.0.dev7 → dicom_dre-1.0.0.dev8}/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 <!-- version list -->
 
+## v1.0.0-dev.7 (2026-07-30)
+
+### Bug Fixes
+
+- **ci**: Handle missing gh-pages branch on first docs deploy
+  ([`7788b48`](https://github.com/susom/dicom-dre/commit/7788b481225bfe09a9d1e8fdc4580bb7baf71655))
+
+
 ## v1.0.0-dev.6 (2026-07-29)
 
 ### Bug Fixes

{dicom_dre-1.0.0.dev7 → dicom_dre-1.0.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dicom-dre
-Version: 1.0.0.dev7
+Version: 1.0.0.dev8
 Summary: DICOM De-identification & Redaction Engine
 Project-URL: repository, https://github.com/susom/dicom-dre
 Author-email: Stanford <people@stanford.edu>
@@ -25,10 +25,10 @@ Description-Content-Type: text/markdown
 
 # DICOM-DRE
 
-A fast, reproducible DICOM de-identification and redaction engine.
+A reproducible DICOM de-identification and redaction engine.
 
 `dicom-dre` removes protected health information (PHI) from DICOM instances in
-two places where it commonly hides:
+two places where it commonly appears:
 
 - **Burned-in pixel PHI.** A declarative device catalog matches each instance to
   a known device and acquisition variant (by manufacturer, model, modality,
@@ -85,11 +85,11 @@ validation, not as a turnkey configuration.
 
 Each instance resolves to one terminal outcome:
 
-- `DEIDENTIFIED` — metadata scrubbed, pixel regions blanked as required, written
+- `DEIDENTIFIED`: metadata scrubbed, pixel regions blanked as required, written
   to the output directory.
-- `FILTERED` — the instance matched a deny rule (for example an unsupported
-  modality or device) and was intentionally not emitted.
-- `QUARANTINED` — processing failed; the instance was not emitted.
+- `FILTERED`: the instance matched a deny rule (for example an unsupported
+  modality or device) and was not emitted.
+- `QUARANTINED`: processing failed; the instance was not emitted.
 
 ## Installation
 
@@ -145,10 +145,10 @@ assert jpeg_dct_accelerator_available(), "JPEG DCT C accelerator is not compiled
 
 Select a de-identification profile with `--profile`:
 
-- `default` — full metadata scrub with re-derived UIDs.
-- `lds` — HIPAA limited data set (retains dates).
-- `lds-no-dob` — limited data set without date of birth.
-- `pixels-only` — pixel scrubbing with minimal metadata changes.
+- `default`: full metadata scrub with re-derived UIDs.
+- `lds`: HIPAA limited data set (retains dates).
+- `lds-no-dob`: limited data set without date of birth.
+- `pixels-only`: pixel scrubbing with minimal metadata changes.
 
 ### Free-text redaction tools
 
@@ -162,8 +162,14 @@ dicom-dre redactor redact --input input.csv --output output.csv
 # Preview redactions side by side
 dicom-dre redactor quality-check input.csv
 
+# Interactively review flagged tokens and add them to the allowlist
+dicom-dre redactor quality-check input.csv --interactive
+
 # List unique tokens to help curate an allowlist
 dicom-dre redactor show-tokens --input input.csv
+
+# Add one or more tokens to the allowlist
+dicom-dre redactor allow-token TERM1 TERM2
 ```
 
 Pass `--allowlist <file.csv-or-path>` to use a custom allowlist and

{dicom_dre-1.0.0.dev7 → dicom_dre-1.0.0.dev8}/README.md

@@ -1,9 +1,9 @@
 # DICOM-DRE
 
-A fast, reproducible DICOM de-identification and redaction engine.
+A reproducible DICOM de-identification and redaction engine.
 
 `dicom-dre` removes protected health information (PHI) from DICOM instances in
-two places where it commonly hides:
+two places where it commonly appears:
 
 - **Burned-in pixel PHI.** A declarative device catalog matches each instance to
   a known device and acquisition variant (by manufacturer, model, modality,
@@ -60,11 +60,11 @@ validation, not as a turnkey configuration.
 
 Each instance resolves to one terminal outcome:
 
-- `DEIDENTIFIED` — metadata scrubbed, pixel regions blanked as required, written
+- `DEIDENTIFIED`: metadata scrubbed, pixel regions blanked as required, written
   to the output directory.
-- `FILTERED` — the instance matched a deny rule (for example an unsupported
-  modality or device) and was intentionally not emitted.
-- `QUARANTINED` — processing failed; the instance was not emitted.
+- `FILTERED`: the instance matched a deny rule (for example an unsupported
+  modality or device) and was not emitted.
+- `QUARANTINED`: processing failed; the instance was not emitted.
 
 ## Installation
 
@@ -120,10 +120,10 @@ assert jpeg_dct_accelerator_available(), "JPEG DCT C accelerator is not compiled
 
 Select a de-identification profile with `--profile`:
 
-- `default` — full metadata scrub with re-derived UIDs.
-- `lds` — HIPAA limited data set (retains dates).
-- `lds-no-dob` — limited data set without date of birth.
-- `pixels-only` — pixel scrubbing with minimal metadata changes.
+- `default`: full metadata scrub with re-derived UIDs.
+- `lds`: HIPAA limited data set (retains dates).
+- `lds-no-dob`: limited data set without date of birth.
+- `pixels-only`: pixel scrubbing with minimal metadata changes.
 
 ### Free-text redaction tools
 
@@ -137,8 +137,14 @@ dicom-dre redactor redact --input input.csv --output output.csv
 # Preview redactions side by side
 dicom-dre redactor quality-check input.csv
 
+# Interactively review flagged tokens and add them to the allowlist
+dicom-dre redactor quality-check input.csv --interactive
+
 # List unique tokens to help curate an allowlist
 dicom-dre redactor show-tokens --input input.csv
+
+# Add one or more tokens to the allowlist
+dicom-dre redactor allow-token TERM1 TERM2
 ```
 
 Pass `--allowlist <file.csv-or-path>` to use a custom allowlist and

{dicom_dre-1.0.0.dev7 → dicom_dre-1.0.0.dev8}/docs/about/history.md

@@ -1,6 +1,6 @@
 # History
 
-`dicom-dre` grew out of a de-identification workflow built on the MIRC CTP
+`dicom-dre` originated from a de-identification workflow built on the MIRC CTP
 (Clinical Trial Processor) engine. This page records that background. It is not
 a reference for configuring the engine; the device catalog and profiles
 documented elsewhere in these docs have replaced the behavior described here.
@@ -24,8 +24,8 @@ dimensions. Pixel rules paired a matching signature with one or more
 Two problems motivated the rewrite:
 
 - The filter and pixel scripts encoded the same device signatures twice, once to
-  decide acceptance and again to place scrub regions, so the two files drifted
-  apart as maintainers added devices.
+  decide acceptance and again to place scrub regions, so the two files diverged
+  as maintainers added devices.
 - The expression syntax was code rather than data, which made the rule set hard
   to inspect, test, and validate.
 
@@ -38,7 +38,7 @@ its scrub regions together. See [Device catalog](../concepts/device-catalog.md).
 
 De-identification profiles now express the metadata handling that a CTP
 anonymizer template previously expressed. See
-[Profiles](../concepts/profiles.md) for the profiles shipped in this repository.
+[Profiles](../concepts/profiles.md) for the profiles included in this repository.
 
 ## Acknowledgement
 

{dicom_dre-1.0.0.dev7 → dicom_dre-1.0.0.dev8}/docs/about/provenance.md

@@ -1,14 +1,14 @@
 # Provenance and Portability
 
-The bundled device catalog and free-text allowlist come from studies on a single
-PACS at one medical research center. The catalog's device rules, pixel scrub
+The bundled device catalog and free-text allowlist come from studies derived from a single
+PACS at a medical research center. The catalog's device rules, pixel scrub
 regions, and allowlisted vocabulary reflect the scanner fleet and reporting
 conventions seen there. They are unlikely to be complete or correct for a
 different site.
 
 ## What is site-specific
 
-The following ship with `dicom-dre` but encode assumptions about one site:
+The following are distributed with `dicom-dre` but encode assumptions about one site:
 
 - **Device rules.** Each catalog entry matches a specific device by
   manufacturer, model, modality, software version, and image dimensions. Devices
@@ -47,5 +47,5 @@ The [Local validation](../guides/local-validation.md) guide describes these
 steps in detail. The [Extending the catalog](../guides/extending-the-catalog.md)
 guide covers adding new device entries.
 
-Treat the shipped catalog and allowlist as a starting point that requires local
+Treat the included catalog and allowlist as a starting point that requires local
 validation, not as a turnkey configuration.

{dicom_dre-1.0.0.dev7 → dicom_dre-1.0.0.dev8}/docs/about/testing.md

@@ -1,6 +1,6 @@
 # Testing
 
-The project uses pytest. Tests live in `tests/unit/` and mirror the structure of
+The project uses pytest. Tests reside in `tests/unit/` and mirror the structure of
 `src/dicom_dre/`.
 
 ## Running the test suite