zettelforge 2.4.2__tar.gz → 2.5.1__tar.gz

zettelforge-2.5.1/.github/CODEOWNERS

@@ -0,0 +1,8 @@
+# Default rule: require @rolandpg for all changes
+* @rolandpg
+
+# Critical security-sensitive paths
+.github/workflows/ @rolandpg
+.github/ @rolandpg
+pyproject.toml @rolandpg
+setup.py @rolandpg

zettelforge-2.5.1/.github/workflows/ci.yml

@@ -0,0 +1,158 @@
+name: CI
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+
+    - name: Set up Python
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      with:
+        python-version: '3.12'
+
+    - name: Install linting tools
+      run: pip install ruff
+
+    - name: Lint with ruff
+      run: ruff check src/zettelforge/
+
+    - name: Format check with ruff
+      run: ruff format --check src/zettelforge/
+
+  # GOV-009 §"Vulnerability Response": runs on every PR, fails on
+  # HIGH/CRITICAL. Token-free complement to Snyk (which gates on
+  # SNYK_TOKEN being set as a repo secret). Audit H-5.
+  pip-audit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+    - name: Set up Python
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      with:
+        python-version: '3.12'
+    - name: Install pip-audit
+      run: pip install pip-audit
+    - name: Audit dependencies (any reported vuln blocks)
+      run: |
+        pip install -e ".[dev]" || pip install -e "."
+        # pip-audit fails non-zero on any reported vuln. Add
+        # --ignore-vuln=CVE-... with a citation when the finding is
+        # explicitly accepted per GOV-009 §"Vulnerability Response".
+        #
+        # CVE-2026-3219: vulnerability in `pip` itself (the package
+        # manager), not a project dependency. The runner's pip is
+        # supplied by GitHub's setup-python image and is not something
+        # ZettelForge's pyproject can pin or upgrade. Risk-accepted
+        # because the pip vulnerability surface is exposed during
+        # install, not at runtime; CI builds in ephemeral runners with
+        # no persistent state. Re-evaluate when GitHub's images ship a
+        # patched pip.
+        pip-audit --strict --vulnerability-service=osv \
+          --ignore-vuln=CVE-2026-3219
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.12', '3.13']
+
+    steps:
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        # If [dev] install fails, fall back to bare install + manually
+        # add the pytest deps. Parenthesizing the fallback prevents shell
+        # precedence from running the "pytest pytest-cov pytest-asyncio"
+        # step when [dev] already succeeded (audit L-4).
+        pip install -e ".[dev]" || (pip install -e "." && pip install pytest pytest-cov pytest-asyncio)
+
+    - name: Pre-download fastembed model
+      run: |
+        python -c "from fastembed import TextEmbedding; TextEmbedding('nomic-ai/nomic-embed-text-v1.5-Q')"
+
+    - name: Test with pytest
+      env:
+        ZETTELFORGE_BACKEND: sqlite
+        ZETTELFORGE_EMBEDDING_PROVIDER: fastembed
+      run: |
+        # GOV-007 §"Coverage Requirements" mandates ≥80% line / ≥70% branch.
+        # We start the ratchet at 67 (matches governance/controls.yaml's
+        # current declaration) so today's pipeline does not break, and #51
+        # tracks raising it toward 80% across v2.5.x. Audit finding H-2.
+        pytest tests/ -v --cov=zettelforge --cov-report=xml --cov-report=term-missing --cov-fail-under=67
+
+    - name: Upload coverage
+      if: matrix.python-version == '3.12'
+      uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: false
+
+  governance:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+
+    - name: Set up Python
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      with:
+        python-version: '3.12'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        # See "Install dependencies" comment above (audit L-4).
+        pip install -e ".[dev]" || (pip install -e "." && pip install pytest pytest-cov)
+
+    - name: GOV-012 — Logging compliance tests
+      env:
+        ZETTELFORGE_BACKEND: sqlite
+      run: |
+        pytest tests/test_logging_compliance.py -v
+
+    - name: Governance spec-drift check
+      run: |
+        pytest tests/test_governance_spec_drift.py -v
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [test, governance]
+
+    steps:
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+
+    - name: Set up Python
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      with:
+        python-version: '3.12'
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build package
+      run: python -m build
+
+    - name: Check package
+      run: twine check dist/*

{zettelforge-2.4.2 → zettelforge-2.5.1}/.github/workflows/docs.yml

@@ -14,8 +14,8 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
         with:
           python-version: '3.12'
       - run: pip install mkdocs-material

{zettelforge-2.4.2 → zettelforge-2.5.1}/.github/workflows/publish.yml

@@ -11,10 +11,10 @@ jobs:
       id-token: write  # trusted publishing
 
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
 
     - name: Set up Python
-      uses: actions/setup-python@v6
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
       with:
         python-version: '3.12'
 
@@ -25,4 +25,4 @@ jobs:
       run: python -m build
 
     - name: Publish to PyPI
-      uses: pypa/gh-action-pypi-publish@release/v1
+      uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b

{zettelforge-2.4.2 → zettelforge-2.5.1}/.github/workflows/snyk-security.yml

@@ -17,10 +17,10 @@ jobs:
       actions: read
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
 
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
         with:
           python-version: '3.12'
 
@@ -30,7 +30,7 @@ jobs:
           pip install -e ".[dev]" || pip install -e "."
 
       - name: Set up Snyk CLI
-        uses: snyk/actions/setup@master
+        uses: snyk/actions/setup@9adf32b1121593767fc3c057af55b55db032dc04
         env:
           SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
 
@@ -44,21 +44,28 @@ jobs:
             echo "has_token=true" >> "$GITHUB_OUTPUT"
           fi
 
+      # GOV-009 §"Vulnerability Response" + GOV-011 §"Testing Phase":
+      # HIGH/CRITICAL Snyk findings must fail the gate. Audit H-5 found
+      # both Snyk steps suffixed with `|| true`, so real findings shipped
+      # silently. Now: --severity-threshold=high so MEDIUM stays advisory
+      # and only HIGH/CRITICAL break the build. SARIF is still emitted via
+      # --sarif-file-output even when the test fails (snyk-code) so the
+      # subsequent Upload SARIF step has artifacts to publish.
       - name: Snyk Code test (SAST)
         if: steps.check_token.outputs.has_token == 'true'
-        run: snyk code test --sarif > snyk-code.sarif || true
+        run: snyk code test --sarif-file-output=snyk-code.sarif --severity-threshold=high
         env:
           SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
 
       - name: Snyk Open Source test (SCA)
         if: steps.check_token.outputs.has_token == 'true'
-        run: snyk test --all-projects || true
+        run: snyk test --all-projects --severity-threshold=high
         env:
           SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
 
       - name: Upload SARIF to GitHub
         if: steps.check_token.outputs.has_token == 'true'
-        uses: github/codeql-action/upload-sarif@v4
+        uses: github/codeql-action/upload-sarif@b25d0ebf40e5b63ee81e1bd6e5d2a12b7c2aeb61
         with:
           sarif_file: snyk-code.sarif
         continue-on-error: true

{zettelforge-2.4.2 → zettelforge-2.5.1}/CHANGELOG.md

@@ -6,6 +6,120 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [2.5.1] - 2026-04-25
+
+Hotfix release. Surfaced during the v2.5.0 perf benchmark run.
+
+### Fixed
+
+- **`KnowledgeGraph._cache_edge` crashed on legacy-schema edges**.
+  Long-running deployments accumulated `kg_edges.jsonl` entries written
+  by a now-removed pre-v2.5.x writer that used
+  `{source_id, target_id, relation_type}` instead of the canonical
+  `{from_node_id, to_node_id, relationship}` keys. The loader hard-failed
+  with `KeyError: 'from_node_id'` on the first such row, taking down
+  every `recall()` and `synthesize()` that touches the KG. Affects any
+  workspace with mixed-schema edge history; observed locally with 189k
+  edges where ~80k were the legacy shape.
+  `_normalize_edge_schema()` now remaps legacy keys to canonical on load
+  and silently drops entries that are still un-normalizable, with a
+  count logged at WARNING so operators can see the skip volume.
+  Six new regression tests in `tests/test_kg_edge_schema.py` cover
+  pass-through, remap, missing-fields, non-dict, mixed-batch, and
+  corrupt-JSON cases. The previously-broken environment-dependent
+  `test_basic.py::test_ingest_relationship` now passes deterministically.
+
+## [2.5.0] - 2026-04-25
+
+Compliance-driven minor release. Closes every CRITICAL and HIGH audit
+finding except H-3 (mypy strict) and the ANN slice of H-1, both of
+which need per-module ratchet plans. Also adds two new optional LLM
+backends, a Presidio PII detector, and supply-chain hardening.
+
+### Added
+
+- **RFC-011 — Local LLM backend selection** (#104). New `local_backend`
+  config knob picks between `llama-cpp-python` (GGUF) and
+  `onnxruntime-genai` (ONNX) at runtime. Both ship as optional extras
+  (`pip install zettelforge[local]` or `[local-onnx]`).
+- **RFC-012 — LiteLLM unified provider** (#108). Routes to 100+
+  upstream LLM providers via the LiteLLM SDK. Optional extra
+  (`pip install zettelforge[litellm]`); the base package never imports
+  it unless the SDK is present.
+- **RFC-013 — Microsoft Presidio PII detection** (#118). Optional PII
+  validator with three policies (`log` / `redact` / `block`),
+  configurable via `governance.pii.*`. CTI allowlist excludes
+  `IP_ADDRESS` / `URL` / `DOMAIN_NAME` from detection so legitimate
+  threat-intel indicators flow through unmodified. Soft dependency —
+  `pip install zettelforge[pii]` to activate; the base package never
+  imports `presidio_analyzer` unless the SDK is present.
+- **GOV-009 Snyk SCA + SAST declared in `controls.yaml`** (#114). The
+  spec-drift validator now walks every `.github/workflows/*.yml` so
+  controls whose CI step lives outside `ci.yml` (Snyk's separate
+  workflow) can be honestly declared.
+- **GOV-006 solo-maintainer compensating controls** (#117). New
+  `controls.yaml` entry pins the existing CI gates (lint, tests,
+  governance spec-drift) as compensating controls for the GOV-006
+  two-person review rule that cannot be physically satisfied with one
+  human maintainer. CODEOWNERS updated with explanatory comment.
+- **`SECURITY.md` + CODEOWNERS** added to the repo root for vulnerability
+  disclosure and review attribution.
+
+### Changed
+
+- **All GitHub Actions are now SHA-pinned** (audit H-5 hardening). Every
+  `uses: org/repo@vX` reference replaced with `uses: org/repo@<full-sha> # vX.Y.Z`
+  to prevent supply-chain attacks via tag rewrites.
+- **Ruff rule set ratcheted to GOV-003 §"Tooling and Automation" minus
+  ANN** (#106 + #107 + #109 + #111 + #113). Active `select` list:
+  `{E, F, I, W, N, T20, B, UP, SIM, RUF, S}`. Per-line `# noqa: SXXX`
+  annotations document each accepted exception (best-effort fallbacks,
+  non-crypto RNG, `?`-bound SQL with constant column lists).
+  `RUF002`/`RUF003` ignored globally for stylistic en-dash and ×.
+- **CI install-step shell precedence fixed** (#112). The
+  `pip install -e ".[dev]" || pip install -e "." && pip install pytest...`
+  chain parsed as `(A || B) && C`, so the pytest install ran on
+  every success path including when `[dev]` already provided pytest.
+  Wrapped the fallback in parentheses.
+- **CONTRIBUTING.md accuracy** (#115). Documents `ruff format`
+  (project hasn't used black for a while) and lists what CI actually
+  enforces so new contributors have a green-build target.
+
+### Compliance audit closure (`tasks/compliance-audit-2026-04-25.md`)
+
+| Severity | Finding | Status |
+|---|---|---|
+| CRITICAL | C-1 branch protection | CLOSED (with required status checks) |
+| CRITICAL | C-2 fabricated `no_hardcoded_secrets` claim | CLOSED (#100) |
+| HIGH | H-1 ruff full select per GOV-003 | CLOSED for {E,F,I,W,N,T20,B,UP,SIM,RUF,S}; ANN ratcheting per-module |
+| HIGH | H-2 coverage threshold not enforced | CLOSED (#100) |
+| HIGH | H-4 GOV-006 / CODEOWNERS solo-maintainer | CLOSED on the zettelforge side (#117); GOV-006 doc amendment in `rolandpg/governance` repo is separate scope |
+| HIGH | H-5 SCA gate + SHA-pinned actions | CLOSED (#102 + #114 + SHA-pin commit) |
+| MEDIUM | M-1 bare `except:` in production | CLOSED (#100) |
+| MEDIUM | M-3 OCSF `timezone_offset` field | CLOSED (#100) |
+| LOW | L-4 CI install-step shell precedence | CLOSED (#112) |
+
+Outstanding: H-3 (mypy --strict in CI; needs per-module ratchet plan
+for 393 errors across 38 files), M-2 (rewrite GOV-016 to match the
+YAML-frontmatter practice already in use), M-4 (lock file), H-1 ANN
+ratchet (121 findings across 38 files).
+
+## [2.4.3] - 2026-04-25
+
+Patch release. Three small but consequential fixes that landed during the post-v2.4.2 Vigil live-test session, plus the standalone `compact_lance` maintenance script and Nexus's Tier 0/1/2 LLM observability instrumentation.
+
+### Added
+
+- **OCSF `metadata.product.version` self-correct** (#96). `ocsf.py:_resolve_product_version()` now prefers the source `pyproject.toml` reachable from `__file__` and falls back to `importlib.metadata.version("zettelforge")`. Editable installs — where `git checkout vX.Y.Z` updates the source tree but not the installed-metadata record — no longer emit stale version strings. Observed live on Vigil 2026-04-24: v2.4.2 source was emitting `product.version=2.4.1` events because the editable-install metadata hadn't been refreshed.
+- **`ZETTELFORGE_LOG_LEVEL` env var honored** (#96). `log.py:get_logger()` now resolves the log level via env var → `config.yaml log.level` → INFO default. Operators can flip DEBUG without editing code or restarting agent boot order. Resolves the "config.yaml `log.level=DEBUG` was dead code" trap hit on Vigil 2026-04-24, where the auto-configure hardcoded INFO and locked `_configured=True` before any caller could read config.
+- **Fastembed preload** (#96). New `vector_memory.preload_embedding_model()` invoked from `MemoryManager.__init__`. Moves the ~800 ms fastembed model-load cost off the first `remember()` and onto agent startup. Best-effort, no-op when `provider != fastembed`. Phase 0.5 measurement: cold `construct=799ms` vs warm `construct=37ms`.
+- **`compact_lance` maintenance script** (#94). New `python -m zettelforge.scripts.compact_lance` for offline LanceDB shard maintenance. Discovers all `<name>.lance/` tables under `<data-dir>/vectordb/`, supports `--dry-run` / `--table` / `--all` / `--mode {compact,optimize}` / `--force`, emits a per-table JSON report with before/after fragment count, on-disk bytes, row count, and elapsed seconds. Operationalized the Phase 0.5 cleanup intervention (see "Vigil incident response" below).
+- **Tier 0/1/2 LLM observability** (#95, Nexus). `ollama_provider.py` now logs every LLM call (model, prompt_chars, response_chars, response_preview, prompt_preview, duration_ms, eval_count, prompt_eval_count, done_reason). `memory_evolver.py` retries log prompt and raw response previews instead of just `neighbor_id`. `fact_extractor.py` empty completions now emit `parse_failed{schema="fact_extraction", reason="empty_completion"}` (`fact_extractor.py:69-71`) instead of silently returning `[]`. `entity_indexer.py` LLM extractions log prompt previews. `structlog.contextvars`-based `trace_id` propagates through `remember()` so every event in a single note's pipeline shares one correlation key.
+
+### Operational notes
+
+The 2026-04-24/25 Vigil live-test session — driven by the v2.4.2 Phase 0.5 instrumentation — found and fixed a 5.66 GB LanceDB version-history bloat on Vigil's `notes_cti` shard. `cleanup_old_versions()` shrank it 5.69 GB → 29 MB and collapsed `remember()` p95 from 49.8 s → ~250 ms. Full evidence in `docs/superpowers/research/2026-04-25-phase-0.5-attribution.md`. The periodic-cleanup feature itself ships in v2.5.0 as RFC-009 Phase 1.5; the v2.4.3 `compact_lance` script supports the one-shot operator workflow until then.
+
 ## [2.4.2] - 2026-04-24
 
 Patch release bundling the RFC-010 enrichment-pipeline hotfix with the

zettelforge-2.5.1/CODEOWNERS

@@ -0,0 +1,13 @@
+# ZettelForge Code Owners
+# These users are automatically requested for review on PRs.
+#
+# Solo-maintainer mode (see governance/controls.yaml GOV-006): the
+# project currently has one human maintainer, so the GOV-006 §"Approval
+# Requirements" two-person rule cannot be physically satisfied. Until a
+# second maintainer is added, the compensating controls declared under
+# GOV-006 in controls.yaml (CI-green required, lint, governance
+# spec-drift, plus GOV-009 SCA/SAST gates) substitute for a second set
+# of human eyes. The audit trail of compensating controls is recoverable
+# from CI logs and branch-protection settings.
+
+* @rolandpg

{zettelforge-2.4.2 → zettelforge-2.5.1}/CONTRIBUTING.md

@@ -18,10 +18,16 @@ No external services (Ollama, TypeDB, Docker) are required for development. Zett
 2. Make your changes
 3. Run tests: `pytest tests/ -v`
 4. Run linting: `ruff check src/zettelforge/`
-5. Run formatting: `black src/zettelforge/`
-6. Commit with clear messages
+5. Run formatting: `ruff format src/zettelforge/`
+6. Commit with a Conventional Commits message (see "Commit Messages" below)
 7. Push and create a pull request
 
+CI enforces the same `ruff check` and `ruff format --check` invocations
+plus `pytest --cov-fail-under=67`, `pip-audit`, governance spec-drift,
+and Snyk SCA/SAST. The full active rule set is `{E, F, I, W, N, T20,
+B, UP, SIM, RUF, S}` per GOV-003 §"Tooling and Automation"; only ANN
+remains and is being ratcheted per-module.
+
 ## Where to contribute
 
 All of `src/zettelforge/` is MIT-licensed and open to contributions.

{zettelforge-2.4.2 → zettelforge-2.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zettelforge
-Version: 2.4.2
+Version: 2.5.1
 Summary: ZettelForge: Agentic Memory System with vector search, knowledge graph, and synthesis
 Project-URL: Homepage, https://github.com/rolandpg/zettelforge
 Project-URL: Documentation, https://docs.threatrecall.ai
@@ -46,8 +46,19 @@ Provides-Extra: extensions
 Requires-Dist: zettelforge-enterprise>=2.1.0; extra == 'extensions'
 Provides-Extra: langchain
 Requires-Dist: langchain-core>=0.2.0; extra == 'langchain'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.60.0; extra == 'litellm'
 Provides-Extra: local
 Requires-Dist: llama-cpp-python>=0.3.0; extra == 'local'
+Provides-Extra: local-all
+Requires-Dist: llama-cpp-python>=0.3.0; extra == 'local-all'
+Requires-Dist: onnxruntime-genai>=0.4.0; extra == 'local-all'
+Provides-Extra: local-onnx
+Requires-Dist: onnxruntime-genai>=0.4.0; extra == 'local-onnx'
+Provides-Extra: pii
+Requires-Dist: presidio-analyzer>=2.2.0; extra == 'pii'
+Requires-Dist: presidio-anonymizer>=2.2.0; extra == 'pii'
+Requires-Dist: spacy>=3.5.0; extra == 'pii'
 Provides-Extra: web
 Requires-Dist: fastapi>=0.100.0; extra == 'web'
 Requires-Dist: uvicorn>=0.20.0; extra == 'web'

zettelforge-2.5.1/SECURITY.md

@@ -0,0 +1,75 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+This is a solo-maintainer project. For security-related issues:
+- Open a GitHub Security Advisory in the repository
+- Tag with `security` label
+- Expect acknowledgement within 48 hours
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| latest release | ✅ |
+| master branch | ✅ (CI gates) |
+| older releases | ❌ |
+
+## Supply Chain Security
+
+This project implements:
+- SHA-pinned GitHub Actions (all third-party actions pinned by commit SHA)
+- PyPI trusted publishing (OIDC, no long-lived tokens)
+- pip-audit on every CI run (HIGH/CRITICAL must pass)
+- Dependabot for weekly dependency updates
+- Snyk SAST scanning on every push/PR
+
+## Known Security Architecture
+
+See [THREAT_MODEL.md](docs/THREAT_MODEL.md) for the complete STRIDE threat model.
+
+### Data at Rest
+
+- Notes, the knowledge graph, and the entity index are stored in a local SQLite database (WAL mode) under the configured data directory. No encryption at rest is applied by ZettelForge itself -- encrypt the filesystem or volume at the OS level for sensitive deployments.
+- LanceDB vector index files live alongside the SQLite database and carry the same recommendation.
+
+### PII Protection
+
+- As of v2.5.0 (RFC-013), optional PII detection via Microsoft Presidio scans content before `remember()` storage. Three modes: log (discovery), redact (compliance), block (strict). Disabled by default. Requires `pip install zettelforge[pii]` to activate.
+- Raw PII text is never written to structured logs. Only entity type and detection score are recorded.
+
+### LLM Provider Security
+
+- Four providers: `local` (in-process, no network), `ollama` (localhost HTTP), `litellm` (cloud APIs), `mock` (testing). Each is configurable via `llm.provider` in config.yaml.
+- `local` provider is fully offline. `ollama` runs on localhost only. `litellm` makes outbound HTTPS calls to configured cloud APIs.
+- API keys use `${ENV_VAR}` resolution -- never committed to YAML. Redacted from all log output via `LLMConfig.__repr__`.
+- Provider timeout is configurable (default 60s). LiteLLM provider supports configurable retry count.
+
+### Injection Defenses
+
+- As of v2.1.1, all LanceDB query expressions are parameterized. String-interpolated queries were present in v2.1.0 and earlier (see CVE advisory, if issued, or CHANGELOG v2.1.1 P0-3).
+
+### File Locking
+
+- As of v2.1.1, all JSONL and entity index write paths use `fcntl.flock()` exclusive locks to prevent concurrent-write corruption.
+
+### Audit Logging
+
+- All security-relevant operations emit OCSF v1.3 structured events via `structlog`. Authorization decisions, API activity, and file activity are auditable in any SIEM that ingests JSON logs.
+
+### Air-Gap Deployments
+
+- ZettelForge supports fully offline operation (fastembed ONNX + llama-cpp-python). No telemetry or external calls are made in this configuration.
+
+## Disclosure Policy
+
+ZettelForge follows a coordinated disclosure model:
+
+1. Reporter submits vulnerability privately via email.
+2. We acknowledge within 48 hours and begin assessment.
+3. We develop and test a fix on a private branch.
+4. We notify the reporter when a fix is ready and agree on a disclosure date.
+5. We release the fix and publish a security advisory simultaneously.
+6. We credit the reporter in the advisory (unless they opt out).
+
+We ask reporters to give us a reasonable time to fix issues before public disclosure. We will not take legal action against good-faith security researchers who follow this policy.