mdrack 1.3.0__tar.gz

mdrack-1.3.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

mdrack-1.3.0/.github/workflows/offline-release-matrix.yml

@@ -0,0 +1,90 @@
+name: offline-release-matrix
+
+on:
+  workflow_dispatch:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ['3.11', '3.12']
+    env:
+      UV_NO_PROGRESS: '1'
+      GIT_CONFIG_COUNT: '1'
+      GIT_CONFIG_KEY_0: core.autocrlf
+      GIT_CONFIG_VALUE_0: 'false'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: '0.11.15'
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Install development environment from lock
+        shell: bash
+        run: |
+          uv lock --check
+          uv sync --all-extras --frozen
+      - name: Enter offline verification boundary
+        shell: bash
+        run: echo "UV_OFFLINE=1" >> "$GITHUB_ENV"
+      - name: Ruff gate
+        shell: bash
+        run: uv run ruff check src/ tests/ packages/mdrack-core/src/ packages/mdrack-media/src/ packages/mdrack-sqlite/src/
+      - name: Mypy gate
+        shell: bash
+        run: uv run mypy packages/mdrack-core/src/mdrack_core packages/mdrack-sqlite/src/mdrack_sqlite
+      - name: Unit and integration gate
+        if: runner.os == 'Linux'
+        shell: bash
+        run: uv run pytest -m 'not e2e and not privacy'
+      - name: Windows package contract gate
+        if: runner.os == 'Windows'
+        shell: bash
+        run: uv run pytest tests/unit/test_offline_release_matrix.py tests/unit/test_v13_release_contract.py
+      - name: Offline E2E gate
+        if: runner.os == 'Linux'
+        shell: bash
+        run: uv run pytest -m e2e
+      - name: Privacy gate
+        if: runner.os == 'Linux'
+        shell: bash
+        run: uv run pytest -m privacy
+      - name: Dependency and architecture gates
+        shell: bash
+        run: |
+          uv run python scripts/check_no_forbidden_deps.py
+          uv run python scripts/check_core_boundaries.py
+          uv run python scripts/check_sqlite_boundaries.py
+          uv run python scripts/check_media_boundaries.py
+          uv run python -m compileall -q scripts src packages/mdrack-core/src packages/mdrack-media/src packages/mdrack-sqlite/src
+      - name: Build and audit all distributions offline
+        shell: bash
+        run: uv run python scripts/offline_release_matrix.py --output-dir "${{ runner.temp }}/mdrack-release-artifacts" --smoke --allow-index-for-smoke-provisioning
+      - name: Documentation and whitespace gates
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          uv run python scripts/check_v13_release_packet.py --artifacts-dir "${{ runner.temp }}/mdrack-release-artifacts"
+          git diff --check
+      - name: Windows artifact evidence gate
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          uv run python scripts/check_v13_release_packet.py --skip-quality-replay --artifacts-dir "${{ runner.temp }}/mdrack-release-artifacts"
+          git diff --check
+      - name: Upload release evidence
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-${{ matrix.os }}-py${{ matrix.python-version }}
+          path: ${{ runner.temp }}/mdrack-release-artifacts/

mdrack-1.3.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# uv
+.python-version
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+Thumbs.db
+Desktop.ini
+.DS_Store
+
+# Logs and local agent/evaluation artifacts
+*.log
+logs/
+.local-reports/
+.serena/
+
+# Debug
+md_writer_debug.log
+
+# SQLite (generated, not source)
+*.sqlite
+*.sqlite3
+.mdrack/
+
+# User reference materials (not part of MDRack source)
+tests/Агенты Hermes/
+tests/*.md
+
+# Environment
+.env
+.env.*
+
+# The root application lock is committed; nested experimental package locks stay local.
+**/uv.lock
+!/uv.lock

mdrack-1.3.0/AGENTS.md

@@ -0,0 +1,111 @@
+# AGENTS.md — MDRack agent router
+
+## Project
+
+MDRack is a local Python 3.11+ CLI and embedded library for indexing Markdown,
+storing structural metadata and search indexes in SQLite, creating embeddings
+through an LM Studio HTTP endpoint, and returning stable JSON retrieval results.
+
+- Repository/workdir: repository root of the current checkout
+- Kanban board: `mdrack`
+- Package manager: `uv`
+- Persistent database: SQLite only
+- Public entry points: Click CLI and `MDRackEngine`
+
+## Start here
+
+1. Read this router.
+2. Inspect `git status --short`; preserve unrelated changes.
+3. Load only instructions matching the files and operation below.
+4. Treat current code and migrations as authoritative over prose and historical plans.
+5. Make the smallest scoped change and verify it with real commands.
+
+## Setup and verification
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check src/ tests/
+uv run ruff check packages/mdrack-core/src/ packages/mdrack-sqlite/src/
+uv run mypy packages/mdrack-core/src/mdrack_core packages/mdrack-sqlite/src/mdrack_sqlite
+uv run python scripts/check_no_forbidden_deps.py
+uv run python scripts/check_core_boundaries.py
+uv run python scripts/check_sqlite_boundaries.py
+git diff --check
+```
+
+Use `uv run` for Python commands. Do not use the system `pip` or create an
+untracked package-manager workflow.
+
+## Instruction routing
+
+| Trigger or scope | Load |
+|---|---|
+| Architecture, module boundaries, public surfaces, dependency direction | `instructions/ARCH.system.instructions.md` |
+| SQLite schema, migrations, repositories, FTS, vectors, assets, identity | `instructions/DATA.sqlite.instructions.md` |
+| Tests, fixtures, quality gates, evidence claims | `instructions/TEST.quality-gates.instructions.md` |
+| Current architecture docs, diagrams, links, historical/current labeling | `instructions/DOCS.architecture.instructions.md` |
+| Create or edit `AGENTS.md` or `instructions/` | `instructions/DOCS.instruction-style-guide.instructions.md` |
+| Investigate, plan, estimate, or decompose without implementation | `instructions/WORKFLOW.plan-orchestration.instructions.md` |
+| Implement, fix, refactor, or edit project files | `instructions/WORKFLOW.build-orchestration.instructions.md` |
+| Commit, merge, switch branch, resolve conflicts, push, or alter history | `instructions/WORKFLOW.git-safety.instructions.md` |
+| Turn requirements into an implementation-ready specification | `instructions/WORKFLOW.requirements-to-spec.instructions.md` |
+| Add, change, or audit logging and diagnostics | `instructions/OBS.logging.instructions.md` |
+| Explicit visual/image inspection or MCP-assisted visual evidence | `instructions/TOOLING.mcp-instrument.instructions.md` |
+
+More-specific instructions override broader workflow guidance. If an instruction
+contradicts verified code, stop, follow the code for the immediate task, and repair
+the stale instruction in the same documentation slice when allowed.
+
+## Product invariants
+
+- Application services normally depend on domain types and ports; adapters implement ports.
+  The current bounded exception is `IndexingService`, which imports and constructs
+  `MarkdownItParser` as its default when no parser is injected. Do not broaden this
+  concrete dependency; changing it requires a scoped architecture task.
+- Click must not leak into `MDRackEngine` or application/domain code.
+- SQLite is the only persistent database. Do not add a vector database.
+- `packages/mdrack-sqlite/` is the single generic resource catalog/search adapter
+  owner; app compatibility paths delegate/re-export and package code never imports `mdrack`.
+- Embeddings use LM Studio over HTTP. Do not add `torch`, `transformers`,
+  `sentence-transformers`, or direct model loading.
+- Indexing must not modify source Markdown or fetch external assets.
+- Public retrieval uses logical identities and portable source locators. Do not
+  expose new SQLite record IDs as public contracts.
+- Production reranking remains unsupported unless an approved architecture change
+  updates code, tests, contracts, ADRs, and instructions together.
+- Do not add a GUI, web server, or MCP server to MDRack.
+- Keep PEP 8, type hints, and justified `# noqa` usage.
+- Production code uses `logging`; stdout is reserved for documented CLI output.
+- Never commit credentials, user content, absolute private paths, databases,
+  generated indexes, logs, caches, or vault material.
+
+## Source-of-truth hierarchy
+
+1. Runtime behavior and public tests.
+2. SQL migrations `src/mdrack/storage/sqlite/migrations/0000...` onward.
+3. Domain types, ports, application services, adapters, CLI, and public API.
+4. Current architecture and contract documentation.
+5. Historical plans, which explain intent but not current behavior.
+
+Current contract references include `docs/cli-contracts.md` and
+`docs/decisions/0001-reranking-deferred.md`. Files under `docs/plans/` and legacy
+root plans are historical unless explicitly marked active for the current task.
+
+## Change discipline
+
+- Respect the active task's editable/read-only boundaries.
+- Do not add features outside the approved scope or dependencies without a recorded reason.
+- Update schema documentation and migration notes with every schema change.
+- Update routing whenever an instruction is added, renamed, or removed.
+- Update current documentation when architecture, public contracts, limitations,
+  or verification commands change.
+- Do not claim live, external, or full-suite evidence that was not actually run.
+
+## Git boundary
+
+Read-only Git inspection is allowed. Commits, pushes, branch changes, merges,
+rebases, resets, staging, and history edits require explicit task/user scope and
+`WORKFLOW.git-safety.instructions.md`. Never initialize, commit, or push merely
+because the repository exists; this repository has an `origin`, but remote state
+must be checked live before any remote claim.

mdrack-1.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VladimirMonin
+
+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.

mdrack-1.3.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: mdrack
+Version: 1.3.0
+Summary: Local command-line Markdown knowledge rack for AI agents
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: markdown-it-py>=4.0
+Requires-Dist: mdrack-core==1.0.0rc1
+Requires-Dist: mdrack-media==1.0.0rc1
+Requires-Dist: mdrack-sqlite==1.0.0rc2
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=13.0
+Requires-Dist: toml>=0.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MDRack
+
+MDRack 1.3.0 is a local Python 3.11+ command-line and embedded retrieval rack for
+Markdown, typed metadata, timed transcripts, frame-caption text, and explicitly
+supplied images. Its primary operational user is an agent working under a human
+operator's explicit authority over locally held data.
+
+The application depends on standalone `mdrack-core` and `mdrack-sqlite`
+distributions. The first is the stdlib-only provider/persistence-neutral kernel;
+the second is the stdlib-plus-core generic resource catalog/search adapter. The
+`mdrack` distribution owns Markdown/image ingestion, app migration generations,
+LM Studio integration, Click JSON commands, and `MDRackEngine`; it vendors neither
+package.
+
+## Quick start
+
+```bash
+uv sync --all-extras
+uv run mdrack --help
+uv run mdrack guide
+mkdir -p ./notes
+uv run mdrack --root ./notes init
+uv run mdrack --root ./notes scan --provider fake
+uv run mdrack --root ./notes search "architecture" --mode text
+```
+
+This is an offline installation smoke: fake embeddings are deterministic test
+data, not semantic-quality evidence. Configure LM Studio before ordinary
+semantic or hybrid use; see [Getting started](docs/getting-started.md) and the
+[CLI guide](docs/getting-started.md#static-cli-guide).
+
+## Agent-first work with human data
+
+For a real task, an agent first identifies whether it is using the source-checkout
+command (`uv run mdrack`) or an already installed `mdrack` command, then asks for
+an explicit data root and the exact operation to perform. Keep private sources
+outside this repository and out of shell history, reports, and commits. The static
+guide and `--help` are read-only discovery steps; `init`, `scan`, explicit ingest,
+rebuild, delete, and provider/model actions change derived local state and must be
+named and authorized before the agent runs them.
+
+An authorized workflow can scan Markdown in the chosen root or ingest one selected
+raw text/Markdown file, image with caller-supplied text, WAVE file, or ISO-BMFF
+video. The WAVE and ISO-BMFF paths require the caller to opt in to a selected local
+adapter executable; MDRack does not provide built-in transcription, decoding, or
+visual analysis. Search by text and optional scope, retain only returned logical
+IDs and portable locators or time/line evidence, then use a new CLI process with
+the same root to run `status` against the same derived store. Source files remain
+unchanged. The complete safe sequence and its evidence boundary are in
+[Getting started](docs/getting-started.md#agent-workflow-for-authorized-human-data),
+[operations](docs/operations.md#agent-workflow-and-private-data), and the shipped
+[MDRack agent skill](skills/mdrack/SKILL.md).
+
+A real acceptance claim is stronger than this quick start: it requires an agent to
+exercise the installed public surface with separately authorized human-like private
+data while checking source immutability and privacy. Synthetic/offline checks are
+supporting evidence only; they do not substitute for that run.
+
+The CLI also provides read, files, status, doctor, rebuild, eval, and
+LM Studio model-management commands. Host applications can use
+`MDRackEngine` without importing Click.
+
+## How it works
+
+1. The default markdown-it adapter parses UTF-8 Markdown into source blocks
+   with H1–H6 heading paths and exact line/character provenance.
+2. Markdown image syntax contributes only safe textual alt/alias prose; paths and
+   referenced files are never inspected or indexed as assets.
+3. The app projects documents into typed core resources and writes a complete
+   graph atomically to the fixed SQLite catalog at `<store>/catalog.sqlite3`.
+4. Core retrieval accepts ready lexical/vector branches, applies scope filters
+   before limits, groups resource evidence, and performs deterministic weighted RRF.
+5. Explicit image ingestion stores derived caption/OCR text and ready vectors,
+   never source bytes; duplicate and whole-resource similarity use logical IDs.
+
+## Documentation
+
+- [Getting started: installation, configuration, CLI, and engine](docs/getting-started.md)
+- [MDRack agent skill](skills/mdrack/SKILL.md) — self-contained terminal workflow
+- [Operations, diagnostics, privacy, and troubleshooting](docs/operations.md)
+- [Development guide for humans and coding agents](docs/development.md)
+- [Current architecture index](docs/current-architecture/README.md)
+- [System overview](docs/current-architecture/system-overview.md)
+- [Indexing and structural chunking](docs/current-architecture/indexing-and-chunking.md)
+- [SQLite persistence and current schema](docs/current-architecture/sqlite-persistence.md)
+- [Text, semantic, and hybrid retrieval](docs/current-architecture/retrieval.md)
+- [Asset handling](docs/current-architecture/assets.md)
+- [CLI and embedded interfaces](docs/current-architecture/public-interfaces.md)
+- [Current limitations](docs/current-architecture/limitations.md)
+- [Completed MDRack 1.3 compact-storage plan (historical)](docs/plans/2026-07-24-v1.3-compact-storage-sqlite-vec.md)
+- [MDRack 1.3.0 release notes and source-publication status](docs/release-1.3.md)
+- [MDRack 1.1 local release](docs/release-1.1.md)
+- [CLI contracts](docs/cli-contracts.md)
+- [v0.3 compatibility registry](docs/compatibility/v0.3-compatibility-registry.md)
+- [Recovery procedures](docs/recovery.md)
+- [ADR-0001: reranking deferred](docs/decisions/0001-reranking-deferred.md)
+- [ADR-0002: provider/storage-neutral core](docs/decisions/0002-provider-storage-neutral-core.md)
+- [ADR-0004: SQLite operating envelope](docs/decisions/0004-sqlite-operating-envelope.md)
+- [Offline release verification](docs/offline-release-verification.md) — supported distribution cells, matrix evidence, and strict no-live gates
+- [Licensing and commercial use](docs/licensing.md) — MIT policy, commercial-use boundary, and Windows bundle gate
+- [Third-party runtime notices](THIRD_PARTY_NOTICES.md) — exact locked resolver graph and upstream-license obligations
+- [v0.4 W5-CI contract](docs/contracts/v0.4-w5-ci-contract.md)
+- [v0.4 offline release-candidate packet](docs/evidence/v0.4-release-packet.md) — exact stage/release/DoD evidence and non-claims
+- [v0.4 public-surface compatibility ledger](docs/compatibility/v0.4-public-surface-ledger.json)
+- [v0.3 release evidence](docs/evidence/v0.3-release-gate.md)
+
+Files under `docs/plans/` and the legacy architecture/design documents are
+historical unless explicitly marked as an active plan. They are not the current
+product contract.
+
+## Images
+
+Markdown image syntax never starts image ingestion. It preserves eligible alt or
+textual alias once as ordinary prose and discards target/path/title/dimensions.
+`mdrack image ingest` is a separate explicit local-file operation. Caption/OCR
+text is caller-supplied or produced by an injected extractor; live LM Studio use
+requires an explicit provider choice. Source bytes remain outside SQLite and are
+never modified.
+
+## Known limitations
+
+- SQLite is the only persistent database. Fresh compact generations use canonical
+  float32 vectors and the builtin exact Python scan; there is no ANN/vector
+  extension dependency in the base distribution.
+- Structural `overlap_chars` is currently not consumed, so structural chunks do
+  not overlap.
+- Production reranking is disabled. `rerank_rank` and `rerank_score` remain
+  `null`; non-null reranker injection fails closed.
+- MDRack indexes supplied transcripts and frame-caption text; it does not
+  transcribe raw audio or perform pixel/visual or acoustic search.
+- The CLI also accepts explicitly authorized local raw-media adapters:
+  `ingest audio SOURCE_PATH --source-ref REF --allow-external-stt
+  --stt-command COMMAND` for RIFF/WAVE input and `ingest raw-video SOURCE_PATH
+  --source-ref REF --allow-external-video-extractor
+  --video-extractor-command COMMAND` for ISO-BMFF input. These shell-free
+  stdin adapters are caller-selected; they are not built-in transcription,
+  decoding, pixel/acoustic search, or provider quality evidence.
+- Provider-free and real-source checks prove retrieval behavior and source
+  integrity, not universal semantic quality from a live embedding model.
+- Legacy `files` and `sections` inspection commands still expose internal record
+  IDs; new resource/image/search contracts expose logical IDs only.
+- The resource-core schema lives in one fixed `catalog.sqlite3`. There is no
+  candidate-generation cutover or runtime rollback; destructive recreation is
+  separately authorized.
+
+See the complete [limitations ledger](docs/current-architecture/limitations.md).
+
+## Verification and recovery
+
+Run the complete offline verification suite with `scripts/verify.sh` on Linux or
+`scripts/verify.ps1` on Windows. The release-specific cells and strict gates are
+documented in [offline release verification](docs/offline-release-verification.md):
+they cover `mdrack`, `mdrack-core`, `mdrack-media`, and `mdrack-sqlite` as wheel
+and sdist, Linux/Windows × Python 3.11/3.12 evidence, offline E2E/privacy lanes,
+and installed smoke. Provider calls, network fallback, and remote execution are
+not part of the default path. Fixed-catalog recovery and destructive recreation
+boundaries are documented in [recovery](docs/recovery.md).
+
+For a reproducible Windows executable build, see
+[Windows EXE build](docs/windows-exe-build.md).
+
+## License and commercial use
+
+MDRack is standard MIT software. Commercial use, modification, redistribution,
+sublicensing, and sale are allowed, provided that the exact copyright and
+permission notice — `Copyright (c) 2026 VladimirMonin` — stays with copies or
+substantial portions. MDRack is provided without warranty. This is a project
+license summary, not legal advice or clearance for a particular distribution.
+
+The policy for the four Python distributions and future Windows bundle is in
+[licensing and commercial use](docs/licensing.md).
+The exact locked resolver dependency graph, including the Windows-only
+`colorama` branch and `certifi`/MPL-2.0, is recorded in
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Resolver-installed
+dependencies are not relicensed by MDRack and are not bundled in the four base
+Python wheel/sdist artifacts.

mdrack-1.3.0/README.md

@@ -0,0 +1,176 @@
+# MDRack
+
+MDRack 1.3.0 is a local Python 3.11+ command-line and embedded retrieval rack for
+Markdown, typed metadata, timed transcripts, frame-caption text, and explicitly
+supplied images. Its primary operational user is an agent working under a human
+operator's explicit authority over locally held data.
+
+The application depends on standalone `mdrack-core` and `mdrack-sqlite`
+distributions. The first is the stdlib-only provider/persistence-neutral kernel;
+the second is the stdlib-plus-core generic resource catalog/search adapter. The
+`mdrack` distribution owns Markdown/image ingestion, app migration generations,
+LM Studio integration, Click JSON commands, and `MDRackEngine`; it vendors neither
+package.
+
+## Quick start
+
+```bash
+uv sync --all-extras
+uv run mdrack --help
+uv run mdrack guide
+mkdir -p ./notes
+uv run mdrack --root ./notes init
+uv run mdrack --root ./notes scan --provider fake
+uv run mdrack --root ./notes search "architecture" --mode text
+```
+
+This is an offline installation smoke: fake embeddings are deterministic test
+data, not semantic-quality evidence. Configure LM Studio before ordinary
+semantic or hybrid use; see [Getting started](docs/getting-started.md) and the
+[CLI guide](docs/getting-started.md#static-cli-guide).
+
+## Agent-first work with human data
+
+For a real task, an agent first identifies whether it is using the source-checkout
+command (`uv run mdrack`) or an already installed `mdrack` command, then asks for
+an explicit data root and the exact operation to perform. Keep private sources
+outside this repository and out of shell history, reports, and commits. The static
+guide and `--help` are read-only discovery steps; `init`, `scan`, explicit ingest,
+rebuild, delete, and provider/model actions change derived local state and must be
+named and authorized before the agent runs them.
+
+An authorized workflow can scan Markdown in the chosen root or ingest one selected
+raw text/Markdown file, image with caller-supplied text, WAVE file, or ISO-BMFF
+video. The WAVE and ISO-BMFF paths require the caller to opt in to a selected local
+adapter executable; MDRack does not provide built-in transcription, decoding, or
+visual analysis. Search by text and optional scope, retain only returned logical
+IDs and portable locators or time/line evidence, then use a new CLI process with
+the same root to run `status` against the same derived store. Source files remain
+unchanged. The complete safe sequence and its evidence boundary are in
+[Getting started](docs/getting-started.md#agent-workflow-for-authorized-human-data),
+[operations](docs/operations.md#agent-workflow-and-private-data), and the shipped
+[MDRack agent skill](skills/mdrack/SKILL.md).
+
+A real acceptance claim is stronger than this quick start: it requires an agent to
+exercise the installed public surface with separately authorized human-like private
+data while checking source immutability and privacy. Synthetic/offline checks are
+supporting evidence only; they do not substitute for that run.
+
+The CLI also provides read, files, status, doctor, rebuild, eval, and
+LM Studio model-management commands. Host applications can use
+`MDRackEngine` without importing Click.
+
+## How it works
+
+1. The default markdown-it adapter parses UTF-8 Markdown into source blocks
+   with H1–H6 heading paths and exact line/character provenance.
+2. Markdown image syntax contributes only safe textual alt/alias prose; paths and
+   referenced files are never inspected or indexed as assets.
+3. The app projects documents into typed core resources and writes a complete
+   graph atomically to the fixed SQLite catalog at `<store>/catalog.sqlite3`.
+4. Core retrieval accepts ready lexical/vector branches, applies scope filters
+   before limits, groups resource evidence, and performs deterministic weighted RRF.
+5. Explicit image ingestion stores derived caption/OCR text and ready vectors,
+   never source bytes; duplicate and whole-resource similarity use logical IDs.
+
+## Documentation
+
+- [Getting started: installation, configuration, CLI, and engine](docs/getting-started.md)
+- [MDRack agent skill](skills/mdrack/SKILL.md) — self-contained terminal workflow
+- [Operations, diagnostics, privacy, and troubleshooting](docs/operations.md)
+- [Development guide for humans and coding agents](docs/development.md)
+- [Current architecture index](docs/current-architecture/README.md)
+- [System overview](docs/current-architecture/system-overview.md)
+- [Indexing and structural chunking](docs/current-architecture/indexing-and-chunking.md)
+- [SQLite persistence and current schema](docs/current-architecture/sqlite-persistence.md)
+- [Text, semantic, and hybrid retrieval](docs/current-architecture/retrieval.md)
+- [Asset handling](docs/current-architecture/assets.md)
+- [CLI and embedded interfaces](docs/current-architecture/public-interfaces.md)
+- [Current limitations](docs/current-architecture/limitations.md)
+- [Completed MDRack 1.3 compact-storage plan (historical)](docs/plans/2026-07-24-v1.3-compact-storage-sqlite-vec.md)
+- [MDRack 1.3.0 release notes and source-publication status](docs/release-1.3.md)
+- [MDRack 1.1 local release](docs/release-1.1.md)
+- [CLI contracts](docs/cli-contracts.md)
+- [v0.3 compatibility registry](docs/compatibility/v0.3-compatibility-registry.md)
+- [Recovery procedures](docs/recovery.md)
+- [ADR-0001: reranking deferred](docs/decisions/0001-reranking-deferred.md)
+- [ADR-0002: provider/storage-neutral core](docs/decisions/0002-provider-storage-neutral-core.md)
+- [ADR-0004: SQLite operating envelope](docs/decisions/0004-sqlite-operating-envelope.md)
+- [Offline release verification](docs/offline-release-verification.md) — supported distribution cells, matrix evidence, and strict no-live gates
+- [Licensing and commercial use](docs/licensing.md) — MIT policy, commercial-use boundary, and Windows bundle gate
+- [Third-party runtime notices](THIRD_PARTY_NOTICES.md) — exact locked resolver graph and upstream-license obligations
+- [v0.4 W5-CI contract](docs/contracts/v0.4-w5-ci-contract.md)
+- [v0.4 offline release-candidate packet](docs/evidence/v0.4-release-packet.md) — exact stage/release/DoD evidence and non-claims
+- [v0.4 public-surface compatibility ledger](docs/compatibility/v0.4-public-surface-ledger.json)
+- [v0.3 release evidence](docs/evidence/v0.3-release-gate.md)
+
+Files under `docs/plans/` and the legacy architecture/design documents are
+historical unless explicitly marked as an active plan. They are not the current
+product contract.
+
+## Images
+
+Markdown image syntax never starts image ingestion. It preserves eligible alt or
+textual alias once as ordinary prose and discards target/path/title/dimensions.
+`mdrack image ingest` is a separate explicit local-file operation. Caption/OCR
+text is caller-supplied or produced by an injected extractor; live LM Studio use
+requires an explicit provider choice. Source bytes remain outside SQLite and are
+never modified.
+
+## Known limitations
+
+- SQLite is the only persistent database. Fresh compact generations use canonical
+  float32 vectors and the builtin exact Python scan; there is no ANN/vector
+  extension dependency in the base distribution.
+- Structural `overlap_chars` is currently not consumed, so structural chunks do
+  not overlap.
+- Production reranking is disabled. `rerank_rank` and `rerank_score` remain
+  `null`; non-null reranker injection fails closed.
+- MDRack indexes supplied transcripts and frame-caption text; it does not
+  transcribe raw audio or perform pixel/visual or acoustic search.
+- The CLI also accepts explicitly authorized local raw-media adapters:
+  `ingest audio SOURCE_PATH --source-ref REF --allow-external-stt
+  --stt-command COMMAND` for RIFF/WAVE input and `ingest raw-video SOURCE_PATH
+  --source-ref REF --allow-external-video-extractor
+  --video-extractor-command COMMAND` for ISO-BMFF input. These shell-free
+  stdin adapters are caller-selected; they are not built-in transcription,
+  decoding, pixel/acoustic search, or provider quality evidence.
+- Provider-free and real-source checks prove retrieval behavior and source
+  integrity, not universal semantic quality from a live embedding model.
+- Legacy `files` and `sections` inspection commands still expose internal record
+  IDs; new resource/image/search contracts expose logical IDs only.
+- The resource-core schema lives in one fixed `catalog.sqlite3`. There is no
+  candidate-generation cutover or runtime rollback; destructive recreation is
+  separately authorized.
+
+See the complete [limitations ledger](docs/current-architecture/limitations.md).
+
+## Verification and recovery
+
+Run the complete offline verification suite with `scripts/verify.sh` on Linux or
+`scripts/verify.ps1` on Windows. The release-specific cells and strict gates are
+documented in [offline release verification](docs/offline-release-verification.md):
+they cover `mdrack`, `mdrack-core`, `mdrack-media`, and `mdrack-sqlite` as wheel
+and sdist, Linux/Windows × Python 3.11/3.12 evidence, offline E2E/privacy lanes,
+and installed smoke. Provider calls, network fallback, and remote execution are
+not part of the default path. Fixed-catalog recovery and destructive recreation
+boundaries are documented in [recovery](docs/recovery.md).
+
+For a reproducible Windows executable build, see
+[Windows EXE build](docs/windows-exe-build.md).
+
+## License and commercial use
+
+MDRack is standard MIT software. Commercial use, modification, redistribution,
+sublicensing, and sale are allowed, provided that the exact copyright and
+permission notice — `Copyright (c) 2026 VladimirMonin` — stays with copies or
+substantial portions. MDRack is provided without warranty. This is a project
+license summary, not legal advice or clearance for a particular distribution.
+
+The policy for the four Python distributions and future Windows bundle is in
+[licensing and commercial use](docs/licensing.md).
+The exact locked resolver dependency graph, including the Windows-only
+`colorama` branch and `certifi`/MPL-2.0, is recorded in
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Resolver-installed
+dependencies are not relicensed by MDRack and are not bundled in the four base
+Python wheel/sdist artifacts.