# dctx > dctx turns any folder into the smallest correct context for a task, offline, with byte-stable output that prompt caches can reuse. dctx is an advanced tool with several ways to use it. Used well, it cuts irrelevant text from selected tool answers. It does not save tokens by default; savings depend on a system reusing byte-identical, prefix-stable context. Extra calls can add tokens. If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything. ## About this file - Publisher: TEJL - tvornica elektroničkih jedinica i logike. TEJL.com: https://tejl.com/; TEJL.hr: https://tejl.hr/. - This is llms-full.txt: the facts, every public HTML page, the document pack and captured CLI help and examples. The other entry points: https://www.dctx.internet.technology/llms-small.txt, https://www.dctx.internet.technology/llms.txt. - Engine: dctx 1.3.1. Document captures are the unedited output of the dctx binary on a copy of the documents, recorded by https://github.com/Eris-Margeta/dctx/blob/main/tools/website/capture.py; the site check re-runs them and fails on any byte of drift. Read the pack at https://www.dctx.internet.technology/llms-full.txt. - Docs commit: 5f0b8b6e4560a9c6e2dc361fd7d2e6c33f9ba3b0 (2026-11-17T15:05:30+01:00), the last commit that changed one of the documents. - Command: `dctx pack . --include /docs/START.md --include /docs/WHY-DCTX.md --include /README.md --include /docs/MODALITIES.md --include /docs/guides/MAP-MODE.md --include /docs/guides/AGENTS-SNIPPET.md --include /docs/guides/PLUGINS.md --include /docs/SPEC.md --include /docs/ADR-014-Privacy-Guarantees-and-Ignore-Semantics.md --include /docs/ADR-018-Language-Coverage.md --include /docs/design/contracts/DTS-v2.md --include /docs/ADR-003-Templating-Engine.md --include /docs/CRATE-MAP.md --include /docs/CLI-EXIT-CODES.md --include /docs/BENCHMARK-20261030.md --include /docs/research/stability-20261105/REPORT.md --include /docs/research/trail-code-2026-10/REPORT.md --include /RELEASING.md --include /CONTRIBUTING.md --include /SECURITY.md --include /TRADEMARK.md --include /MAINTENANCE.md --include /crates/dctx-template/templates/default.dctx_template --include /crates/dctx-template/templates/stamped.dctx_template` - Document capture budget: 90,806 of 110,000 estimated tokens (ceil(2 * UTF-8 bytes / 7)), 24 documents. ## Facts ### What dctx is dctx is an open-source (Apache-2.0) Rust context engine for AI-assisted coding: one local binary that packs a project into one structured block, or answers bounded, byte-stable symbol queries (find, read, neighbors, skeleton) as CLI output. What it is not: - No RAG: no embeddings, no vector search, and the engine never calls a model. - No network: pack, map and cache make no network calls; the release check counts socket calls under strace and fails on any. - No telemetry, not even opt-out. - No agent loop: dctx answers one command at a time; the agent or the human decides what to ask next. ### Version and download - Current version: 1.3.1, released 2026-11-09 (tag `v1.3.1`): https://github.com/Eris-Margeta/dctx/releases/tag/v1.3.1 - Each release on GitHub ships prebuilt archives for Linux x64/ARM64, macOS x64/ARM64 and Windows x64 with a SHA256SUMS file. - Verify a download: `sha256sum --check --ignore-missing SHA256SUMS` - Releases from 1.3.0 also ship keyless cosign signatures, CycloneDX SBOMs, build provenance and offline bundles; see [verification](https://github.com/Eris-Margeta/dctx/blob/main/docs/VERIFYING.md). ### Modalities - CLI (available): `dctx pack PATH` for one structured block (clipboard, file or stdout); `dctx map find|read|neighbors|skeleton|...` for bounded symbol answers. https://www.dctx.internet.technology/cli/ - Task context (available): `dctx pack --for TEXT --budget N`: find, neighbors and read of the names in TEXT, cut to an estimated-token budget. https://www.dctx.internet.technology/docs/map-mode/ - CI and prompt cache (available): Deterministic pack and map output; tree lines carry no timestamps by default, so the prefix stays stable across a touch. https://www.dctx.internet.technology/docs/modalities/#ci--prompt-cache-prefix-stability - Rust library (available from Git): The `dctx` facade crate as a tagged Git dependency; crates.io publication pending. https://www.dctx.internet.technology/docs/modalities/#rust-library-embed-the-facade - Desktop app (preview): A Tauri preview you build from source; a GPUI rebuild is planned. https://www.dctx.internet.technology/docs/modalities/#desktop-app-tauri-preview-today - Python, Node and Go wrappers (Node on npm; Python and Go from CI): Thin `dctx rpc` wrappers, built and tested in CI. Install Node with `npm install @tejl/dctx`, which includes pinned `@tejl/dctx-` optional dependencies; use CI artifacts for Python and Go. https://www.dctx.internet.technology/docs/modalities/#python-node-and-go-wrappers Two scopes, one binary: - System binary: the `dctx` on PATH belongs to you and your agents, and you upgrade it. Interactive agents call this one. - Project binary (Node from npm; Python and Go from CI): a binary installed by a project library lives inside that project (virtualenv, node_modules), pinned and managed by that package manager. Application code and CI call this one; a library never silently falls back to PATH. - Same engine, different owner. `dctx doctor` lists every binary in reach; verify each against SHA256SUMS and its cosign signature. ### Before you start > dctx is an advanced tool with several ways to use it. Used well, it cuts irrelevant text from selected tool answers. It does not save tokens by default; savings depend on a system reusing byte-identical, prefix-stable context. Extra calls can add tokens. If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything. ### Benchmarks Baseline: grep plus reading files. - Measured: 11 November 2026: 20 questions, a private 13-crate Rust workspace, claude-sonnet-5-5, dctx 1.3.0, three repeats per arm. Median total tokens [min, max]: grep plus reads 14,904,014 [14,604,149, 15,622,381]; dctx CLI (warm index) 14,157,974 [11,221,908, 15,613,375]. CLI median tokens were -5.01 % versus grep. On this corpus and model dctx did not save 25 % tokens; the pre-registered rule was not met. Official strict citation recall medians [min, max]: grep 10.10 % [10.10, 20.73]; CLI 14.46 % [8.36, 22.65]. Diagnostic file-level recall medians: 53.77 % and 71.70 %, respectively; diagnostic, not a replacement metric. The claim is accuracy and bounded context, not token savings. dctx on its own does not save tokens by default. Savings depend on a harness or agent system reusing byte-identical, prefix-stable context across long sessions; there is no measured, citable savings figure for such a system yet. One corpus, one model, no significance claim; corpus and raw answers private and cannot be published; dctx 1.3.0 is not current HEAD. Under ~200 files, use grep. https://www.dctx.internet.technology/benchmarks/#grep-read - Measured: Byte stability: the same query on unchanged code returns the same bytes; 33 of 33 text and JSON answers were byte-identical after unrelated edits (Linux only). https://www.dctx.internet.technology/docs/stability/ - Historical: The October and November in-house numbers (run 7: 140 of 140 task questions, cold index and warm latency) measure tool output only, as estimated stdout tokens and raw fact coverage without a model; they are not agent completion rates or session costs. https://www.dctx.internet.technology/benchmarks/ - Hypothesis: That a pack template changes model answer quality or cost is a hypothesis pending an A/B test; nothing on this site measures it. https://www.dctx.internet.technology/templates/ ### Removed in 1.2.0 These existed before 1.2.0 and no longer work. A transcript that uses them describes an old version. - `dctx PATH` (the implicit snapshot command, for example `dctx .`): use `dctx pack PATH`. - the top-level snapshot flags `-d`/`--diff`, `-t`/`--tree` and `-r`/`--reset`: use `dctx pack PATH` with its filters. - the project rule files `.legacyignore` and `.dctxomitcontent`: use `.gitignore` and `.dctxignore`. - `dctx cache gc --legacy` and its export-selection flags: use `dctx cache gc`. ### How to verify a claim - Test suite: `cargo test --workspace --locked --exclude dctx-desktop --exclude dctx-desktop-api` https://github.com/Eris-Margeta/dctx/blob/main/docs/TESTING.md - CI: Every push and pull request runs the suite on Linux, macOS (ARM64 and x64) and Windows, on stable Rust and the minimum supported version 1.91. https://github.com/Eris-Margeta/dctx/actions - No network calls: `scripts/release-check.sh --quick target/release/dctx-cli` https://github.com/Eris-Margeta/dctx/blob/main/scripts/release-check.sh - Byte stability: `python3 docs/research/stability-20261105/verify.py` https://www.dctx.internet.technology/docs/stability/ - Historical benchmark: `docs/research/bench-3way-20261030/run-3way.sh target/release/dctx-cli` https://github.com/Eris-Margeta/dctx/tree/main/docs/research/bench-3way-20261030 - Every output on this site: Recorded from the real binary by tools/website/capture.py; tools/website/check.py re-records and fails on drift. https://github.com/Eris-Margeta/dctx/tree/main/tools/website ## Pages ### Overview - [dctx](https://www.dctx.internet.technology/): dctx is the open-source context engine for AI-assisted development: deterministic, bounded code context for agents and chat, offline, with no telemetry. Apache-2.0. - [Search](https://www.dctx.internet.technology/search/): Search the dctx website. - [Playground offline](https://www.dctx.internet.technology/playground/offline/): The playground service is not reachable right now. - [Page not found](https://www.dctx.internet.technology/404.html): This page does not exist on the dctx website. ### Docs - [Documentation](https://www.dctx.internet.technology/docs/): Specification, guides, benchmark reports and project policies for dctx, rendered from the repository. - [Choose your path](https://www.dctx.internet.technology/start/): dctx is an advanced tool with several ways to use it. Pick the path that matches your work: one giant folder, many small projects, a library in your own tool, or a team rollout. - [One giant folder](https://www.dctx.internet.technology/start/giant-folder/): You work inside one very large tree, for example a 200 GB monorepo, data or document folder. Setup, first command, what to expect and the pitfall to avoid. - [Many smaller projects](https://www.dctx.internet.technology/start/many-projects/): You move between many small and medium repositories during the day. Setup, first command, what to expect and the pitfall to avoid. - [Agent builder embedding a library](https://www.dctx.internet.technology/start/library/): You build an agent, editor or tool and want dctx inside it. Setup, first command, what to expect and the pitfall to avoid. - [Team or organisation admin](https://www.dctx.internet.technology/start/team/): You roll dctx out to a team or a fleet of machines. Setup, first command, what to expect and the pitfall to avoid. - [For AI evaluators](https://www.dctx.internet.technology/for-ai-evaluators/): What dctx is and is not, its version, modalities, benchmark status, removed commands and how to verify every claim. - [Why dctx](https://www.dctx.internet.technology/why/): Why dctx exists, its philosophy, and why byte-identical output keeps the prompt cache hitting. - [README](https://www.dctx.internet.technology/docs/readme/): Installation, quick start, map mode, language tiers and the CLI reference. - [What dctx is](https://www.dctx.internet.technology/docs/start/): The claim and its limits, the advanced-user notice, choose your path, the safe path in ten minutes, responsibilities and the two scopes. - [Choosing how to use dctx](https://www.dctx.internet.technology/docs/modalities/): Clipboard, grep plus reads, long sessions, huge trees, CLI usage and CI. - [Map mode guide](https://www.dctx.internet.technology/docs/map-mode/): Every map verb with examples, budgets, ids and precision labels. - [Agent snippet](https://www.dctx.internet.technology/docs/agents/): The AGENTS.md section that tells coding agents to ask dctx first. - [Plugins guide](https://www.dctx.internet.technology/docs/plugins/): The plugin boundary, capabilities, consent and current limits. - [Specification](https://www.dctx.internet.technology/docs/spec/): The core belief, the five constraints, the ten RAG defect classes, policy and roadmap. - [Privacy guarantees](https://www.dctx.internet.technology/docs/privacy/): Ignore semantics and the full sensitive-file deny list. - [Language coverage (ADR-018)](https://www.dctx.internet.technology/docs/language-coverage/): The three tiers and how a language enters one. - [Template contract (DTS v2)](https://www.dctx.internet.technology/docs/templates-contract/): DTS source v2 and the compiled plan IR v1. - [Templating engine (ADR-003)](https://www.dctx.internet.technology/docs/templating/): Markers, ahead-of-time compilation, the two rendering passes and the data variables. - [CLI exit codes](https://www.dctx.internet.technology/docs/exit-codes/): The exit-code contract for map, pack and languages. - [How dctx works](https://www.dctx.internet.technology/how-it-works/): Five short animations: two scopes of one binary, calls times context, prefix stability, the giant folder and the safe path for new users. ### CLI - [CLI reference](https://www.dctx.internet.technology/cli/): Every dctx command, flag, environment variable, and exit code, captured from the dctx binary. - [Languages](https://www.dctx.internet.technology/languages/): The 50 language families dctx indexes, by tier: full, outline and docs. ### Examples - [Examples](https://www.dctx.internet.technology/examples/): Every dctx command on one sample project, with its exact output, exit code, bytes and estimated tokens. - [Templates](https://www.dctx.internet.technology/templates/): The two built-in dctx templates, their source, their output on the same project and what changes between them. - [Playground](https://www.dctx.internet.technology/playground/): Run the real dctx binary on a sample project or on your own text files, in the browser. ### Evidence - [Measurement evidence](https://www.dctx.internet.technology/docs/benchmark/): Grep plus file reads first; whole-session scope and secondary historical protocols. - [Byte-stability report](https://www.dctx.internet.technology/docs/stability/): Protocol, raw answers and limits of the 33/33 measurement. - [Earlier two-way study](https://www.dctx.internet.technology/docs/benchmark-oct/): October 2026, before call edges: the benchmark that set the roadmap. - [Benchmarks](https://www.dctx.internet.technology/benchmarks/): Grep plus file reads, whole-session accounting, byte stability and secondary historical measurements. ### Project - [Crate map](https://www.dctx.internet.technology/docs/crate-map/): How the Rust workspace is organised. - [Releasing](https://www.dctx.internet.technology/docs/releasing/): How a release is cut and checked. - [Contributing](https://www.dctx.internet.technology/docs/contributing/): How to propose changes, with a DCO sign-off. - [Security policy](https://www.dctx.internet.technology/security/): How to report a vulnerability privately, and what happens next. - [Trademark policy](https://www.dctx.internet.technology/trademark/): What the dctx name and logo may be used for, and what forks may call themselves. - [Maintenance](https://www.dctx.internet.technology/maintenance/): dctx is free under Apache-2.0. Maintenance agreements fund security response, long-term support and priority work. ### Optional - [Changelog](https://www.dctx.internet.technology/changelog/): Every dctx release, from dircontxt 1.0.0 in C to dctx in Rust, with known issues. - [News](https://www.dctx.internet.technology/news/): Releases, measurements and product decisions from the dctx project. - [dctx 1.1: three more languages, a prefix-stable pack, and a measured lead.](https://www.dctx.internet.technology/news/dctx-1-1/): Perl, Fortran and Verilog join map mode; dctx pack drops timestamps so prompt caches hit; the three-way benchmark and the byte-stability measurement are public. - [dctx Desktop is now free. Forever.](https://www.dctx.internet.technology/news/desktop-free-forever/): For individuals, teams and companies. No trial, no seat count, no expiry. - [Our specification, and a benchmark that does not flatter us.](https://www.dctx.internet.technology/news/specification-and-benchmark/): The dctx Context Management Specification, and an isolated comparison with Trail-Code: wins, losses and what comes next. ## Documents [DCTX_LLM_CONTEXT_SNAPSHOT_V1] [DIRECTORY:dctx] 1. Manifest: The section lists all files. - Each entry: [TYPE] RELATIVE_PATH (ID:UNIQUE_ID) - TYPE is [D] for directory, [F] for file. 2. Content Access: To read a specific file: - Find its UNIQUE_ID from the directory tree. - Search for the marker: - The content is between this marker and [D] (ID:ROOT) [F] CONTRIBUTING.md (ID:F001) [F] MAINTENANCE.md (ID:F002) [F] README.md (ID:F003) [F] RELEASING.md (ID:F004) [F] SECURITY.md (ID:F005) [F] TRADEMARK.md (ID:F006) [D] crates (ID:D007) [D] crates/dctx-template (ID:D008) [D] crates/dctx-template/templates (ID:D009) [F] crates/dctx-template/templates/default.dctx_template (ID:F010) [F] crates/dctx-template/templates/stamped.dctx_template (ID:F011) [D] docs (ID:D012) [F] docs/ADR-003-Templating-Engine.md (ID:F013) [F] docs/ADR-014-Privacy-Guarantees-and-Ignore-Semantics.md (ID:F014) [F] docs/ADR-018-Language-Coverage.md (ID:F015) [F] docs/BENCHMARK-20261030.md (ID:F016) [F] docs/CLI-EXIT-CODES.md (ID:F017) [F] docs/CRATE-MAP.md (ID:F018) [F] docs/MODALITIES.md (ID:F019) [F] docs/SPEC.md (ID:F020) [F] docs/START.md (ID:F021) [F] docs/WHY-DCTX.md (ID:F022) [D] docs/design (ID:D023) [D] docs/design/contracts (ID:D024) [F] docs/design/contracts/DTS-v2.md (ID:F025) [D] docs/guides (ID:D026) [F] docs/guides/AGENTS-SNIPPET.md (ID:F027) [F] docs/guides/MAP-MODE.md (ID:F028) [F] docs/guides/PLUGINS.md (ID:F029) [D] docs/research (ID:D030) [D] docs/research/stability-20261105 (ID:D031) [F] docs/research/stability-20261105/REPORT.md (ID:F032) [D] docs/research/trail-code-2026-10 (ID:D033) [F] docs/research/trail-code-2026-10/REPORT.md (ID:F034) # Contributing to dctx Read the [specification](docs/SPEC.md), [crate map](docs/CRATE-MAP.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before making changes. Project contributions are licensed under [Apache-2.0](LICENSE), consistent with [NOTICE](NOTICE). ## Bugs, ideas and questions Search existing [issues](https://github.com/Eris-Margeta/dctx/issues) before opening one. Use the bug or feature template and keep reproductions small. Include the commit or version, OS/architecture, build features, exact command, expected result and actual result. Redact source code, paths, credentials and generated context that you do not have permission to share. Report suspected vulnerabilities privately using [SECURITY.md](SECURITY.md), rather than in an issue or pull request. For other questions, open an issue with what you tried and the relevant documentation link. ## CLI development setup CI tests use `DCTX_CI_RUST` from `tools/release/toolchain.env`; bump it intentionally each Rust release. Use a recent stable Rust toolchain with Cargo; the workspace includes Rust 2024 crates. Clone the repository and run commands from its root: ```zsh git clone https://github.com/Eris-Margeta/dctx cd dctx cargo build --locked -p dctx-cli cargo run --locked -p dctx-cli -- --help ``` Cargo builds **`dctx-cli`**, while help text calls the tool **`dctx`**. See [installation](README.md#installation) for aliases and install choices. Keep changes focused on the relevant crates and preserve unrelated work. The [`dctx` facade](crates/dctx/) serves the CLI and the desktop API; pure engine crates should not acquire filesystem, network or process effects. The [plugin guide](docs/guides/PLUGINS.md) describes effect boundaries and current runtime limitations. ## Validation Start with the CLI and facade checks (some tests validate documentation): ```sh cargo test -p dctx-cli -p dctx --locked ``` For documentation changes, install the Python dependencies using [the website setup](tools/website/README.md), then run `tools/website/.venv/bin/python tools/check-markdown-links.py`. It checks local paths and heading anchors across public Markdown, including HTML and reference links. [Testing](docs/TESTING.md) documents the full Linux/macOS/Windows matrix and local commands. The current [CI workflow](.github/workflows/ci.yml) runs workspace tests on stable Rust and MSRV, plus formatting, Clippy, Rust documentation, licence, website and release checks. Run `cargo fmt --all -- --check` and document public APIs. Follow [Rust house style](docs/STYLE.md) for the plugin boundaries. When editing website source documents, regenerate `website/` and check it using [the website instructions](tools/website/README.md). Before committing, use `check.py --working-tree` to compare your regenerated files with an independent build; CI compares committed output. Capture CLI examples only if output changed. Desktop changes need their platform prerequisites and separate validation; see [the desktop guide](apps/dctx-desktop/README.md). The root `just ci` recipe also invokes desktop setup and is broader than the main CI jobs. ## Developer Certificate of Origin Contributions use the [Developer Certificate of Origin](https://developercertificate.org) (DCO) instead of a contributor license agreement. Sign off each commit to certify that you wrote the change, or otherwise have the right to submit it under Apache-2.0: ```zsh git commit -s ``` The `-s` flag adds a `Signed-off-by:` line with your name and email. Pull requests with unsigned commits will be asked to amend them with `git commit --amend -s`, or to rebase with `--signoff`. ## Pull requests Create a focused branch from `main` and describe the problem, resulting behavior and any compatibility or privacy impact. Add regression coverage for behavior changes and update affected documentation. Check Markdown links and paths when editing guides. Use clear commit messages, for example `fix(cli): reject empty output paths`. In the PR, list the commands you ran, their results, and any checks you could not run. Include relevant OS/build features for platform-specific changes. Avoid unrelated formatting, generated governance files, local caches, credentials and private research artifacts. Maintainers may ask for a smaller change or additional validation before merging. Pull requests, including forks, run on GitHub-hosted CI runners. # dctx maintenance dctx is open source under the Apache-2.0 license and free for any use, including commercial use. A maintenance agreement is how organisations that depend on dctx pay for its upkeep. Paying never changes the license and never closes a feature. ## What an agreement covers - **Security fixes.** Response targets are counted from the moment a report is confirmed: - Critical: a fix or mitigation within 72 hours. - High: a fix within 7 days. - Medium: a fix in the next release. - **Long-term support.** The 1.x line receives backported fixes for 18 months after 2.0 is released. - **Priority on bug reports.** Reports from covered organisations are triaged first. - **A say in the roadmap.** Covered organisations can propose priorities in a regular review. The maintainer keeps the final decision. - **Advance notice of breaking changes.** You hear about a breaking change before it ships, with a migration note. - **Invoice and written commitment.** You receive invoices and a signed maintenance commitment for procurement and vendor review. Security reports still go through [SECURITY.md](SECURITY.md), whatever your tier. ## Tiers | Tier | Who it is for | What you get | |------|---------------|--------------| | Supporter | Individuals and teams who want to fund dctx | Sponsorship and your logo in the README. No service commitments. | | Team | One organisation that depends on dctx | Everything under "What an agreement covers", for one organisation. | | Partner | Organisations that build products on dctx | Team, plus integration help and a named contact. | Supporter sponsorship runs through [GitHub Sponsors](https://github.com/sponsors/Eris-Margeta). Team and Partner agreements are arranged directly. ## Pricing and contact Pricing on request: info@tejl.com Write to that address with your organisation, the tier you want and a contact name. ## Guarantees - Paying never changes the license. dctx stays Apache-2.0 for everyone. - Paying never closes or paywalls a feature. Every feature stays in the open source project. - The core (`pack`) and every modality stay open.

dctx

dctx - context, engineered

Version CI License C/Rust Sponsor dctx Commercial maintenance available No telemetry

Choose your path • Which mode? • Philosophy • Installation • Quick Start • Output examples • Library • Map mode • Security & Privacy • Specification • Website

dctx turns any folder into the smallest correct context for a task, offline, with byte-stable output that prompt caches can reuse.
dctx is an advanced tool with several ways to use it. Used well, it cuts irrelevant text from selected tool answers. It does not save tokens by default; savings depend on a system reusing byte-identical, prefix-stable context. Extra calls can add tokens. If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything.

--- Under ~200 files, use grep. dctx pays off on large repos, multi-hop questions and many agents sharing one index. Run `dctx agent-setup --format agents` (or `--format claude`) for short rules to paste into `AGENTS.md` or `CLAUDE.md`. ## Project status **dctx is not yet stable and not enterprise-ready.** It has been in development since January 2026. Until version 2.0, expect breaking changes often. AI providers keep changing how they optimize context on their side; dctx adapts to those changes quickly, but not in real time. Stability is the goal of 2.0, and the project is working toward it: we see an ultimate solution to this problem, and we are denoising it. dctx began as an internal tool that was never meant to be open-sourced, so parts of it are still messy. It was opened up because colleagues who rely on it needed it in the open, and development continues in public. The founding promise is zero dependencies. Today dctx still has dependencies. The goal is to become the single best context management tool. ## Installation **System binary — available now.** Download the archive for your OS and architecture from [GitHub Releases](https://github.com/Eris-Margeta/dctx/releases/tag/v1.3.1), compare its SHA-256 with the matching entry in `SHA256SUMS`, extract it, and put `dctx` (`dctx.exe` on Windows) on `PATH`. Archives cover Linux x64/ARM64, macOS x64/ARM64 and Windows x64. Releases after 1.2.0 also ship cosign signatures, a CycloneDX SBOM, build provenance and offline bundles; see [verification, provenance and offline installation](docs/VERIFYING.md). ```sh dctx --version ``` **Node wrapper — available on npm from 1.3.1.** Run `npm install @tejl/dctx` to install the [Node wrapper](packaging/npm/dctx/README.md) and its matching pinned `@tejl/dctx-` native package, then `npx @tejl/dctx --version` to check it. The [Python](packages/python/README.md) and [Go](packages/go/README.md) wrappers over `dctx rpc` are built and tested in CI; use their CI artifacts. The [Rust facade](docs/MODALITIES.md#rust-library-embed-the-facade) is available from tagged Git. Use the release archives for the CLI. Follow [the safe path in ten minutes](docs/START.md#safe-path-in-ten-minutes) for one project, CLI setup and whole-session measurement. ## What the output looks like These are real runs on the tiny [kiosk sample](tools/website/sample), captured by [capture.py](tools/website/capture.py) from the release binary. Commands run inside a copy named `kiosk`. For source builds, the executable is `dctx-cli` (or define a `dctx` alias). ### Pack a project The header explains the format, the tree assigns IDs, and file blocks carry paths and line counts. The first 40 output lines follow; only the tail is omitted. `.env` is listed without its contents. ```text $ dctx pack . [DCTX_LLM_CONTEXT_SNAPSHOT_V1] [DIRECTORY:kiosk] 1. Manifest: The section lists all files. - Each entry: [TYPE] RELATIVE_PATH (ID:UNIQUE_ID) - TYPE is [D] for directory, [F] for file. 2. Content Access: To read a specific file: - Find its UNIQUE_ID from the directory tree. - Search for the marker: - The content is between this marker and [D] (ID:ROOT) [F] .env (ID:F001) [F] .gitignore (ID:F002) [F] Cargo.toml (ID:F003) [F] README.md (ID:F004) [F] config.toml (ID:F005) [D] src (ID:D006) [F] src/main.rs (ID:F007) [F] src/store.rs (ID:F008) [F] src/util.rs (ID:F009) [D] tools (ID:D010) [F] tools/report.py (ID:F011) [D] web (ID:D012) [F] web/app.ts (ID:F013) [F] web/format.ts (ID:F014) [Content omitted by pattern rules] target/ [package] name = "kiosk" version = "0.1.0" edition = "2021" … (147 more lines) ``` ### Find a symbol, then read it Pass the exact ID from `find` to `read` to get its metadata and verified source bytes: ```text $ dctx map find greet # kiosk find s:src/util.rs#greet fn L2-4 s:web/app.ts#renderGreeting fn L10-12 ``` ```text $ dctx map read 's:src/util.rs#greet' # kiosk read s:src/util.rs#greet fn src/util.rs pub fn greet(name: &str) -> String { format!("Hello, {}!", title_case(name)) } ``` For structured consumption, `--json` puts the same source bytes in `source_utf8` (one JSON line, shown verbatim): ```text $ dctx map read 's:src/util.rs#greet' --json {"v":2,"place":"kiosk","verb":"read","freshness":{"mode":"strict","state":"verified"},"precision":{"coverage":"syntax","completion":"complete","parser":"dctx-lex-rust/syn-3.0.9"},"records":[{"id":"s:src/util.rs#greet","kind":"fn","path":"src/util.rs","lines":[2,4],"summary":"The greeting shown on the kiosk screen.","summary_source":"doc","signature":null,"span":[44,126],"source_utf8":"pub fn greet(name: &str) -> String {\n format!(\"Hello, {}!\", title_case(name))\n}","edge":null,"direction":null,"target":null,"confidence":null}],"more":0,"next":null} ``` ### Pack for a task `--for` uses the task terms to select find results, neighbors and source reads. `--budget 800` bounds estimated output tokens, not scan size; the footer reports usage and dropped records. ```text $ dctx pack . --for 'greet store' --budget 800 # dctx pack --for budget=800 terms=2 ## find greet s:src/util.rs#greet fn L2-4 s:web/app.ts#renderGreeting fn L10-12 ## find store s:src/store.rs#Order struct L4-8 s:src/store.rs#checksum fn L22-24 s:src/store.rs#encode fn L17-19 ## neighbors s:src/util.rs#greet calls:in:s:src/main.rs#main fn src/main.rs L7 calls:out:s:src/util.rs#title_case fn src/util.rs contains:in:m:src/util.rs module src/util.rs ## neighbors s:src/store.rs#Order contains:in:m:src/store.rs module src/store.rs ## read s:src/util.rs#greet s:src/util.rs#greet fn src/util.rs pub fn greet(name: &str) -> String { format!("Hello, {}!", title_case(name)) } ## read s:src/store.rs#Order s:src/store.rs#Order struct src/store.rs pub struct Order { pub id: u32, pub item: String, pub qty: u32, } # end body_tokens=223 budget=800 dropped=0 ``` ## Which mode? - [CLI and one-off chat](docs/MODALITIES.md#human-one-off-pack-to-clipboard): pack selected source for a prompt or use the interactive terminal. - [Agents, short tasks](docs/MODALITIES.md#short-agent-task-grep-can-be-enough): compare with grep plus narrow file reads first. - [Agents, long sessions and huge trees](docs/MODALITIES.md#huge-trees-scope-before-indexing): scope the root, find symbols and read exact source. - [Libraries](docs/MODALITIES.md#rust-library-embed-the-facade): embed the Rust facade today; install the [Node wrapper](packaging/npm/dctx/README.md) with `npm install @tejl/dctx`, or use CI artifacts for the Python and Go wrappers. - [CI and prompt caching](docs/MODALITIES.md#ci--prompt-cache-prefix-stability): pin inputs and measure byte stability and provider cache behavior. - [Desktop](docs/MODALITIES.md#desktop-app-tauri-preview-today): build the Tauri 0.11 preview; the GPUI rebuild is planned. ## Measured, in the open The baseline is **grep plus reading files**. The [11 November whole-session benchmark](docs/BENCHMARK-20261111.md) measured 20 questions on a private 13-crate Rust workspace with `claude-sonnet-5-5`, dctx 1.3.0 and three repeats per arm. Median total tokens [min, max]: grep plus reads 14,904,014 [14,604,149, 15,622,381]; dctx CLI (warm index) 14,157,974 [11,221,908, 15,613,375]. **On this corpus and model dctx did not save 25 % tokens.** CLI median tokens were -5.01 % versus grep; the pre-registered success rule was not met. The claim is **accuracy and bounded context**, not token savings: CLI named more required files at about equal or higher token cost. dctx on its own does not save tokens by default. Savings come from a harness or agent system that reuses byte-identical, prefix-stable context across long sessions over a large body of work. It behaves like an advanced caching mechanism, with complete control over every byte of context. There is no measured, citable savings figure for such a system yet. [Why this matters](docs/WHY-DCTX.md#savings-belong-to-the-system). Official strict citation recall medians [min, max]: grep 10.10 % [10.10, 20.73], CLI 14.46 % [8.36, 22.65]. Diagnostic file-level recall medians: 53.77 % and 71.70 %, respectively; this does not replace strict recall. One corpus, one model, three repeats; no significance claim. Corpus and raw answers are private and cannot be published; dctx 1.3.0 is not current HEAD. **Under ~200 files, use grep.** Historical cold indexing of six benchmark corpora took dctx 0.13–1.20 s on one Linux x86_64 runner. This measures CLI wall time, not agent completion time or session cost. [Choosing how to use dctx](docs/MODALITIES.md) covers scoping and CLI usage. [Measurement evidence](docs/BENCHMARK-20261030.md) describes what was measured (tool-output bytes and estimated tokens); other-tool protocols are retained only as secondary historical notes. ## Start and choose your path [What dctx is](docs/START.md), [four user paths](docs/START.md#choose-your-path), [responsibilities](docs/START.md#responsibilities), and [two scopes, one binary](docs/START.md#two-scopes-one-binary) explain setup and ownership. The [documentation index](docs/README.md) groups modalities, scopes, engine behavior, reference material, trust and evaluator evidence. “Smallest correct context” is the goal: selection is lexical and bounded, not a proof of task completeness or a mathematical minimum. Large folders need scoped roots; budgets bound answers, not scans. Provider cache hits and whole-session savings must be measured. See [current limits](docs/MODALITIES.md) and the [specification and roadmap](docs/SPEC.md). ## The core belief: prompt-processing efficiency Send fewer relevant bytes, keep their order stable, and verify exact source. dctx does not use embeddings; it selects lexical symbols and document sections. - **Bounded**: map answers use estimated token budgets and whole records. - **Deterministic**: identical source snapshots and requests give identical bytes. Read the [philosophy](docs/WHY-DCTX.md) and its [testable constraints](docs/SPEC.md#2-the-core-belief-prompt-processing-efficiency). ## Quick Start Try a tiny project (POSIX shell; on Windows use Git Bash): ```sh mkdir dctx-demo cd dctx-demo printf 'def hello(name):\n return f"Hello, {name}!"\n' > hello.py dctx map skeleton hello.py ``` Use the [safe path](docs/START.md#safe-path-in-ten-minutes) or the [runnable pack and map example](examples/README.md). For repeated agent work, see [Map mode: context for agents](docs/guides/MAP-MODE.md). ## Map mode: context for agents From this repository's root: ```zsh dctx map find "Session" ``` Read exact IDs from the result with `dctx map read 'ID' --json`. See the [map guide](docs/guides/MAP-MODE.md) for commands, budgets and limits. ## From source Requires Rust 1.91 or newer. ```sh git clone https://github.com/Eris-Margeta/dctx cd dctx cargo build --locked --release -p dctx-cli ./target/release/dctx-cli --version alias dctx="$PWD/target/release/dctx-cli" ``` Cargo builds `dctx-cli` (`dctx-cli.exe` on Windows); release archives supply `dctx`. For a local source installation, use `cargo install --locked --path crates/dctx-cli` and `alias dctx=dctx-cli`. On Windows, invoke the executable directly or create a PowerShell alias. See [CI coverage and desktop exclusions](docs/TESTING.md). ## Use as a library The public Rust entry point is the [`dctx` facade](crates/dctx), available from Git now; **crates.io publication is pending**. ```toml [dependencies] dctx = { git = "https://github.com/Eris-Margeta/dctx", tag = "v1.3.1" } ``` This example is generated from the [workspace doctest](examples/library/README.md): ```rust use dctx::{memory::{CancelFlag, FixedClock, MemorySource}, *}; let mut source = MemorySource::new(); source.insert_file("hello.rs", b"pub fn hello() {}\n", 0)?; let mut session = Session::builder(source).clock(FixedClock(Timestamp(0))) .cancellation(std::sync::Arc::new(CancelFlag::new())).ceiling(HostCeiling::base()) .selection(SelectionPolicy::from_texts(&RuleTexts::default())).grants(HostGrants::PermitAll) .storage(StoragePolicy::Ephemeral { max_bytes: 8 * 1024 * 1024 }).place("demo").view("pack").build()?; let mut output = VecSink::new(); session.pack(&PackRequest::new(), &mut output)?; println!("{}", std::str::from_utf8(output.as_bytes())?); ``` The host supplies selection rules and storage policy; `FsSource` does not load `.gitignore` automatically. Read the [library integration boundary](docs/MODALITIES.md#rust-library-embed-the-facade) before embedding it. Python, Node and Go wrappers over `dctx rpc` live in [packages/python](packages/python/README.md), [packaging/npm](packaging/npm/dctx/README.md) and [packages/go](packages/go/README.md); they are built and tested in CI. Install the Node wrapper with `npm install @tejl/dctx`; use CI artifacts for Python and Go. ## Versioned pack JSON For a pinned external runtime, use `dctx pack --for 'fix alpha_body' --json`. The `schema` field is `dctx.pack/1`; `dctx pack --schema` prints the shipped [JSON Schema](schemas/dctx.pack-1.schema.json). Every included source fragment carries its relative path, exact byte and line bounds, content SHA-256, and the pack's source snapshot identity. Unknown source commits are explicitly `null`. Within this contract, additive changes increment the minor schema version; breaking changes require a new major schema ID. See the [pack contract and offline reproducible-build recipe](docs/PACK-SCHEMA.md) for span conventions, validation, and the two-build proof. ## CLI Reference ``` Usage: dctx [OPTIONS] dctx pack [PATH] [--output PATH] [--clipboard] [--json] dctx pack [PATH] --for [--budget TOKENS] dctx map [--json] dctx context TARGET [--place PATH] [--budget N] [--json] [--session ID --dedupe] dctx rpc dctx read [OPTIONS] dctx languages [--json|--markdown] dctx doctor [--json] dctx cache status [--json] [--root PATH] dctx cache gc [--dry-run] [--root PATH] [--max-bytes N] dctx cache purge --root PATH [--dry-run] [--yes] dctx cache purge --all [--dry-run] [--yes] dctx cache config [auto on|off] [--max-bytes N] [--ttl-days N] dctx cache auto [--json] dctx template build [--output PATH] dctx template list [--dir PATH] dctx plugin search|install|list|info|enable|disable|remove|update|verify dctx git Pack filters: --ext Only files with these extensions (comma-separated) --binary Include binary files (omitted by default) --empty Only 0-byte files --non-empty Only files with content --large Only files larger than this many megabytes --small Only files smaller than this many megabytes --hidden Only hidden files and directories --debug-ignored List ignored directories without reading them --include Only files matching this ignore-rule glob (repeatable) --exclude Drop files matching this ignore-rule glob (repeatable) --output, -o Write the page to one file --clipboard, -c Copy the page to the clipboard --json Summary report; with --for, versioned dctx.pack/1 JSON --schema Print the pack --for JSON schema without reading a project --tree-stamps=on|off MOD: timestamp on tree lines (default off; on = the 1.0.0 text) Task context (agent cards): --for Map find on the names in , then neighbors and read of the best hits --budget With --for: estimated-token cap, 100..100000 (default 3000) ``` - `dctx context` returns ranked context for a file, symbol name or stable node id; repeated targets in one call share a delivery session. - `dctx rpc` serves the versioned engine protocol used by the language wrappers ([protocol](docs/protocol/README.md)); send `hello` first. - `dctx read` is `dctx map read`. `dctx map export` writes the whole graph as JSON or Mermaid. - `dctx languages` lists every supported language and its tier. - `dctx doctor` lists visible dctx binaries, their scopes, SHA-256 checksums and cache sizes, without network access or cache changes. Run `dctx --help`, `dctx pack --help` and `dctx map --help` for the complete reference and `dctx --version --verbose` for feature and precision limits. See [map commands and limits](docs/guides/MAP-MODE.md), [exit codes](docs/CLI-EXIT-CODES.md), [templates](docs/design/contracts/DTS-v2.md), and [plugins](docs/guides/PLUGINS.md). Native plugin launch is currently refused by the product host; consent alone does not enable it. Organization policy and `dctx policy explain` are planned. ### Language tiers `dctx languages` prints this table (`--json` for tools, `--markdown` for this block) from the one registry that also drives `dctx --version --verbose`; a test fails when the block below differs from it. - **full**: symbols and call edges. Call edges are lexical, not type-resolved: they come from names, scopes and imports, never from a type checker, and ambiguous references are dropped. - **outline**: symbols only; no call edges are promised. Shell function bodies can yield same-file call guesses, but v1 does not promise shell call edges. - **docs**: headed sections. - **Confidence**: `guess` marks the heuristic outline families, and every record from those files carries confidence `guess`; `structural` means a dedicated lexer or deterministic document rules.
Full language table | Language | Tag | Files | Tier | Confidence | |---|---|---|---|---| | Rust | `rust` | `.rs` | full | structural | | JavaScript | `javascript` | `.js`, `.mjs`, `.cjs`, `.jsx` | full | structural | | TypeScript/TSX | `typescript` | `.ts`, `.mts`, `.cts`, `.tsx` | full | structural | | Python | `python` | `.py`, `.pyi` | full | structural | | Go | `go` | `.go` | full | structural | | Java | `java` | `.java` | full | structural | | C/C++ | `c` | `.c`, `.h`, `.cc`, `.cpp`, `.cxx`, `.hpp`, `.hh` | full | structural | | C# | `csharp` | `.cs` | full | structural | | Kotlin | `kotlin` | `.kt`, `.kts` | full | structural | | Ruby | `ruby` | `.rb`, `.rake`, `.gemspec`, `Rakefile`, `Gemfile` | full | structural | | PHP | `php` | `.php`, `.phtml`, `.inc` | full | structural | | Swift | `swift` | `.swift` | full | structural | | Vue/Svelte/Astro/HTML script blocks | `web` | `.vue`, `.svelte`, `.astro`, `.html`, `.htm` | full | structural | | Scala | `scala` | `.scala`, `.sc` | full | guess | | Dart | `dart` | `.dart` | full | guess | | Zig | `zig` | `.zig` | full | guess | | Solidity | `solidity` | `.sol` | full | guess | | Gleam | `gleam` | `.gleam` | full | guess | | Fortran | `fortran` | `.f90`, `.f95`, `.f03`, `.f08`, `.f`, `.for` | full | guess | | Perl | `perl` | `.pl`, `.pm`, `.t`, `.psgi` | full | guess | | Groovy | `groovy` | `.groovy`, `.gradle` | full | guess | | PowerShell | `powershell` | `.ps1`, `.psm1`, `.psd1` | full | guess | | Elixir | `elixir` | `.ex`, `.exs` | full | guess | | Lua | `lua` | `.lua` | full | guess | | OCaml | `ocaml` | `.ml`, `.mli` | full | guess | | R | `r` | `.r` | full | guess | | Julia | `julia` | `.jl` | full | guess | | Haskell | `haskell` | `.hs` | full | guess | | Erlang | `erlang` | `.erl`, `.hrl` | full | guess | | Verilog/SystemVerilog | `verilog` | `.v`, `.vh`, `.sv`, `.svh` | full | guess | | Terraform/HCL | `hcl` | `.tf`, `.tfvars`, `.hcl` | full | guess | | SQL | `sql` | `.sql`, `*.sql.in` | full | guess | | Clojure | `clojure` | `.clj`, `.cljs`, `.cljc`, `.edn` | full | guess | | Common Lisp | `lisp` | `.lisp`, `.lsp`, `.cl` | full | guess | | Scheme | `scheme` | `.scm`, `.ss` | full | guess | | Emacs Lisp | `elisp` | `.el` | full | guess | | JSON/JSONC/TOML/YAML | `config` | `.json`, `.jsonc`, `.toml`, `.yaml`, `.yml` | outline | structural | | Shell | `shell` | `.sh`, `.bash`, `.zsh`, `.bats` | outline | guess | | Makefile | `make` | `.mk`, `Makefile`, `GNUmakefile` | outline | guess | | Dockerfile | `docker` | `Dockerfile`, `Containerfile` | outline | guess | | Protobuf | `proto` | `.proto` | outline | guess | | Pascal | `pascal` | `.pas`, `.pp`, `.dpr` | outline | guess | | GraphQL | `graphql` | `.graphql`, `.gql` | outline | guess | | Nix | `nix` | `.nix` | outline | guess | | Markdown | `markdown` | `.md`, `.markdown` | docs | structural | | Plain text | `text` | `.txt` | docs | structural | | reStructuredText | `rst` | `.rst` | docs | structural | | AsciiDoc | `asciidoc` | `.adoc`, `.asciidoc` | docs | structural | | Org | `org` | `.org` | docs | structural | | LaTeX | `tex` | `.tex` | docs | structural |
## Security & Privacy Pack and map run locally and have **no telemetry**, **call no model** and **make no network calls**. Selection happens before any byte is read, hashed, parsed or cached, and is checked again before output leaves the engine. | Rule file | Behaviour | |---|---| | `.gitignore`, `.dctxignore`, global ignore file | Excluded from normal selection; `--debug-ignored` shows ignored path metadata without reading content | The global ignore file is `/dctx/ignore`: `$XDG_CONFIG_HOME/dctx/ignore` or `~/.config/dctx/ignore` on Linux and macOS, `%APPDATA%\dctx\ignore` on Windows. dctx does not read Git metadata, so `.git/info/exclude` and Git's `core.excludesFile` are **not** applied: copy those patterns into `.dctxignore` or the global ignore file when they must keep files out of a pack. `DCTX_INDEX_IGNORED=1` skips those ignore texts, so leave it unset when relying on them. Built-in sensitive-file and `.git` exclusions still apply. Sensitive files such as `.env`, private keys and credentials are omitted from content reads even with ignore negations; pack may list their names. `.git` at any depth is never listed or read by map, and is never read by pack. Symlinks are never followed; final-component file opens use `O_NOFOLLOW`. dctx decides by file name only: a secret pasted into an ordinary source file is not detected. Inspect context before sharing it. The [privacy contract and deny list](docs/ADR-014-Privacy-Guarantees-and-Ignore-Semantics.md) and [map privacy guide](docs/guides/MAP-MODE.md#index-cache-and-privacy) explain the boundary. Report vulnerabilities privately through [SECURITY.md](SECURITY.md). The [release check](scripts/release-check.sh) tests socket activity under `strace -f` and reports SKIP where tracing cannot run. Plugin network and organization policy designs in the spec include planned features; see [current plugin limits](docs/guides/PLUGINS.md#what-is-not-yet-available). ## Open source and maintenance dctx and its desktop app are [Apache-2.0](LICENSE), copyright Eris Margeta. Every modality stays open. [GitHub Sponsors](https://github.com/sponsors/Eris-Margeta) and [maintenance agreements](MAINTENANCE.md) fund upkeep without changing the license. See [trademark policy](TRADEMARK.md), [NOTICE](NOTICE), [Rust dependencies](THIRD_PARTY.md) and [npm dependencies](THIRD_PARTY_NPM.md). ## Where it comes from dctx started in 2025 as `dircontxt` in C and was rewritten in Rust in 2026. The [changelog](CHANGELOG.md) and [`legacy-c/`](legacy-c/) preserve that history. ## Contributing Read [CONTRIBUTING.md](CONTRIBUTING.md), the [specification](docs/SPEC.md) and [crate map](docs/CRATE-MAP.md). [Website](https://www.dctx.internet.technology/) · [Documentation](docs/README.md) · [For AI evaluators](docs/README.md#for-ai-evaluators) · [llms-small.txt](https://www.dctx.internet.technology/llms-small.txt) · [llms.txt](https://www.dctx.internet.technology/llms.txt) · [llms-full.txt](https://www.dctx.internet.technology/llms-full.txt) # Releasing dctx The current CLI packaging, registry publication, website deployment, secret setup and rollback runbook is [docs/RELEASING.md](docs/RELEASING.md). The desktop app retains its separate `desktop-v*` release workflow. ## Publication gate Before any future production/public release, complete the required production security review and full relevant audit for the exact candidate revision and configuration, including independent review, validators and required sandbox/runtime evidence. The focused DCX-03 static sweep and ordinary CI do not satisfy this prerequisite. Keep findings, residual risks and coverage limits private. Follow the owner policy: select an explicit `/.private/security-audits//run-` evidence directory, verify the entire tree is ignored before writing in a Git project, and use owner-only permissions (exclude it from staging/export for a non-Git project). Use the separate overlay instead of the vendor default path. Any unresolved gate blocker needs explicit informed owner disposition tied to the exact release. A gate pass is not a claim of complete security. The owner must authorize the production tag/publication and deployment. # Security Policy ## Supported versions The current major release receives bug fixes and security fixes in its latest release. When a new major is released, the previous major receives security fixes for **six months after the new major's release date**, then reaches end of support. Older majors receive no fixes. Upgrade to the latest patch within a supported major before checking whether an issue is resolved. We publish fixes in new patch releases; we do not promise a separate patch for every historical minor version. This public policy has no LTS commitment beyond that six-month transition. Include the exact version or commit and build features so maintainers can assess affected versions. ## Reporting a vulnerability **Do not disclose vulnerabilities in public issues or pull requests.** Use [GitHub private vulnerability reporting](https://github.com/Eris-Margeta/dctx/security/advisories/new) or email [info@tejl.com](mailto:info@tejl.com) with a subject beginning `[dctx security]`. If GitHub's private reporting form is unavailable, use email. Maintainers must enable private vulnerability reporting in repository security settings; that GitHub setting is separate from this policy file. Include, where possible: - Affected version or commit, OS/architecture and build features. - The affected component and potential impact (for example ignored-file content disclosure, untrusted plugin execution, or signature verification bypass). - Exact reproduction steps and a minimal synthetic fixture or proof of concept. - Expected and actual results, with sanitized diagnostics. - Whether the issue has been shared elsewhere, and a preferred contact method. - A name or alias for credit, or a request to remain anonymous. Never send private keys, tokens, production data or a generated context export containing confidential code. Use synthetic examples and redact sensitive values. Test only systems and data you own or have explicit permission to assess. ## What counts as a vulnerability dctx is an offline tool, but untrusted repositories, files, archives and plugin inputs still cross security boundaries. Report issues such as: - Disclosure of ignored, excluded or secret-file contents, including through generated context, caches, diagnostics or plugin access. - Arbitrary code execution, sandbox or capability bypass, unsafe plugin execution, or command injection caused by processing untrusted input. - Path traversal, symlink escapes, unintended file modification or unsafe archive extraction outside an authorized destination. - Signature, checksum, provenance or update verification bypass; compromised release artifacts or dependencies affecting supported builds. - A reproducible resource-exhaustion attack from a small malicious input that defeats documented bounds and makes the tool unusable. Ordinary output mistakes, unsupported language coverage, feature requests and performance issues without a security boundary impact belong in public issues. Use private reporting when unsure. Offline operation does not make confidential local data or the release supply chain out of scope. ## Handling and disclosure We acknowledge private vulnerability reports **within 7 days**. We investigate impact, identify affected supported versions and coordinate a fix or mitigation and public disclosure with the reporter. Remediation timing depends on severity and available maintainers; the acknowledgment window is not a promised fix deadline. If acknowledgment has not arrived within 7 days, follow up through the other private channel. Credit is subject to the reporter's consent. We will not take legal action against individuals who discover and report security vulnerabilities in good faith and in accordance with this policy. Please coordinate public disclosure so users can receive a fix or mitigation. For architectural boundaries and current implementation limits, see the [README](README.md#security--privacy) and [plugin guide](docs/guides/PLUGINS.md). Those descriptions are not a security certification. # dctx trademark policy The "dctx" name and logo are trademarks of Eris Margeta. The Apache-2.0 license covers the code only, not these marks. ## Forks and redistribution Forks and redistribution of dctx are welcome under Apache-2.0. Keep the LICENSE and NOTICE files, and state clearly what you changed. ## What needs permission - Calling a modified build, fork or product "dctx", or any name that suggests it is the official dctx. - Using the dctx logo on a modified build, fork, product, website or merchandise. Name a modified build something else, for example "XYZ, based on dctx". Ask for permission if you want to use the logo. ## What is always fine - Unmodified official builds of dctx, redistributed as they are. - Descriptive use of the name, such as "works with dctx", "a dctx plugin" or "built on dctx". To ask for permission, write to info@tejl.com. # ============================================================================== # DCTX TEMPLATE DEFINITION V1 # ============================================================================== # This file defines how the LLM context is formatted. # It consists of three sections: [VARIABLES], [PARTIALS], and [LAYOUT]. # # SYNTAX GUIDE: # - {{VAR_NAME}} : Inserts a configuration variable defined in [VARIABLES]. # - {{{DATA_FIELD}}} : Inserts dynamic data from the project (e.g., file content). # # ============================================================================== [VARIABLES] # --- 1. Syntactic Markers (Granular Control) --- # Defines the exact characters used to wrap tags. # Allows handling XML, HTML, or Custom formats safely. start_marker_open = "<" start_marker_close = ">" end_marker_open = "" # --- 2. Semantic Marker Names --- # Defines the keywords used inside the tags. instr_marker = "INSTRUCTIONS" tree_start_marker = "DIRECTORY_TREE" tree_end_marker = "DIRECTORY_TREE" file_start_marker = "FILE_CONTENT_START" file_end_marker = "FILE_CONTENT_END" # --- 3. Attribute Keys --- # Used inside tags to denote properties. attr_id = "ID" attr_path = "PATH" attr_size = "SIZE" attr_lines = "LINES" attr_mod = "MOD" # --- 4. Branding & Header Config --- folder_denotation_marker = "DIRECTORY" # --- 5. Instructions Block Text --- # This text explains the format to the LLM. It references the variables above # to ensure the instructions always match the actual format used. # Use '\n' for new lines. instructions_text = "1. Manifest: The {{start_marker_open}}{{tree_start_marker}}{{start_marker_close}} section lists all files.\n - Each entry: [TYPE] RELATIVE_PATH ({{attr_id}}:UNIQUE_ID)\n - TYPE is [D] for directory, [F] for file.\n2. Content Access: To read a specific file:\n - Find its UNIQUE_ID from the directory tree.\n - Search for the marker: {{start_marker_open}}{{file_start_marker}} {{attr_id}}="UNIQUE_ID"{{start_marker_close}}\n - The content is between this marker and {{end_marker_open}}{{file_end_marker}} {{attr_id}}="UNIQUE_ID"{{end_marker_close}}" # ============================================================================== # [PARTIALS] # Defines the look of repeated elements (Tree items and Files). # ============================================================================== # --- Tree Entry Partial --- # Context: 'node' object # Available Data: {{{node.type_char}}}, {{{node.path}}}, {{{node.id}}}, {{{node.mod}}}, {{{node.size}}} # The default entry leaves {{{node.mod}}} and {{{node.size_part}}} out: a timestamp or a size changes on an edit or a touch # and would break the byte-stable prefix of the page. Custom templates may still use {{attr_mod}}, {{{node.mod}}}, # {{{node.size}}} and {{{node.size_part}}}; `--tree-stamps=on` selects the stamped built-in (the 1.0.0 text). [PARTIAL:TREE_ENTRY] {{{node.type_char}}} {{{node.path}}} ({{attr_id}}:{{{node.id}}}) # --- File Block Partial --- # Context: 'file' object # Available Data: {{{file.id}}}, {{{file.path}}}, {{{file.lines}}}, {{{file.size}}}, {{{file.content}}} [PARTIAL:FILE_BLOCK] {{start_marker_open}}{{file_start_marker}} {{attr_id}}="{{{file.id}}}" {{attr_path}}="{{{file.path}}}" {{attr_lines}}="{{{file.lines}}}"{{start_marker_close}} {{{file.content}}} {{end_marker_open}}{{file_end_marker}} {{attr_id}}="{{{file.id}}}"{{end_marker_close}} # ============================================================================== # [LAYOUT] # The master structure of the final output file. # Note: The Version Header (e.g. [DCTX_SNAPSHOT_V1]) is hardcoded in the binary # and NOT included here. # ============================================================================== [LAYOUT] [{{folder_denotation_marker}}:{{{project}}}] {{start_marker_open}}{{instr_marker}}{{start_marker_close}} {{instructions_text}} {{end_marker_open}}{{instr_marker}}{{end_marker_close}} {{start_marker_open}}{{tree_start_marker}}{{start_marker_close}} {{{comp.tree}}} {{end_marker_open}}{{tree_end_marker}}{{end_marker_close}} {{{comp.files}}} # ============================================================================== # DCTX TEMPLATE DEFINITION V1 # ============================================================================== # This file defines how the LLM context is formatted. # It consists of three sections: [VARIABLES], [PARTIALS], and [LAYOUT]. # # SYNTAX GUIDE: # - {{VAR_NAME}} : Inserts a configuration variable defined in [VARIABLES]. # - {{{DATA_FIELD}}} : Inserts dynamic data from the project (e.g., file content). # # ============================================================================== [VARIABLES] # --- 1. Syntactic Markers (Granular Control) --- # Defines the exact characters used to wrap tags. # Allows handling XML, HTML, or Custom formats safely. start_marker_open = "<" start_marker_close = ">" end_marker_open = "" # --- 2. Semantic Marker Names --- # Defines the keywords used inside the tags. instr_marker = "INSTRUCTIONS" tree_start_marker = "DIRECTORY_TREE" tree_end_marker = "DIRECTORY_TREE" file_start_marker = "FILE_CONTENT_START" file_end_marker = "FILE_CONTENT_END" # --- 3. Attribute Keys --- # Used inside tags to denote properties. attr_id = "ID" attr_path = "PATH" attr_size = "SIZE" attr_lines = "LINES" attr_mod = "MOD" # --- 4. Branding & Header Config --- folder_denotation_marker = "DIRECTORY" # --- 5. Instructions Block Text --- # This text explains the format to the LLM. It references the variables above # to ensure the instructions always match the actual format used. # Use '\n' for new lines. instructions_text = "1. Manifest: The {{start_marker_open}}{{tree_start_marker}}{{start_marker_close}} section lists all files.\n - Each entry: [TYPE] RELATIVE_PATH ({{attr_id}}:UNIQUE_ID, {{attr_mod}}:TIMESTAMP)\n - TYPE is [D] for directory, [F] for file.\n2. Content Access: To read a specific file:\n - Find its UNIQUE_ID from the directory tree.\n - Search for the marker: {{start_marker_open}}{{file_start_marker}} {{attr_id}}="UNIQUE_ID"{{start_marker_close}}\n - The content is between this marker and {{end_marker_open}}{{file_end_marker}} {{attr_id}}="UNIQUE_ID"{{end_marker_close}}" # ============================================================================== # [PARTIALS] # Defines the look of repeated elements (Tree items and Files). # ============================================================================== # --- Tree Entry Partial --- # Context: 'node' object # Available Data: {{{node.type_char}}}, {{{node.path}}}, {{{node.id}}}, {{{node.mod}}}, {{{node.size}}} [PARTIAL:TREE_ENTRY] {{{node.type_char}}} {{{node.path}}} ({{attr_id}}:{{{node.id}}}, {{attr_mod}}:{{{node.mod}}}{{{node.size_part}}}) # --- File Block Partial --- # Context: 'file' object # Available Data: {{{file.id}}}, {{{file.path}}}, {{{file.lines}}}, {{{file.size}}}, {{{file.content}}} [PARTIAL:FILE_BLOCK] {{start_marker_open}}{{file_start_marker}} {{attr_id}}="{{{file.id}}}" {{attr_path}}="{{{file.path}}}" {{attr_lines}}="{{{file.lines}}}"{{start_marker_close}} {{{file.content}}} {{end_marker_open}}{{file_end_marker}} {{attr_id}}="{{{file.id}}}"{{end_marker_close}} # ============================================================================== # [LAYOUT] # The master structure of the final output file. # Note: The Version Header (e.g. [DCTX_SNAPSHOT_V1]) is hardcoded in the binary # and NOT included here. # ============================================================================== [LAYOUT] [{{folder_denotation_marker}}:{{{project}}}] {{start_marker_open}}{{instr_marker}}{{start_marker_close}} {{instructions_text}} {{end_marker_open}}{{instr_marker}}{{end_marker_close}} {{start_marker_open}}{{tree_start_marker}}{{start_marker_close}} {{{comp.tree}}} {{end_marker_open}}{{tree_end_marker}}{{end_marker_close}} {{{comp.files}}} # ADR-003: Extensible Templating System (DTS) & Compilation Strategy **Status:** current — architectural principle retained; historical examples describe their original release. For shipped behavior and limitations, see the [README](../README.md), [testing guide](TESTING.md) and [specification](SPEC.md). **Date:** 2026-01-08 **Author:** dctx Team **Context:** Users require granular control over the output format to support various AI models. The system must maintain high performance (avoiding expensive parsing on every run) and ensure robustness (instructions matching output). ## 1. Decision: Explicit Marker Definition To ensure future compatibility with non-HTML-like syntax, the templating language separates "Opening" and "Closing" logic for tags into four distinct definitions: * `start_marker_open` (Default: `<`) * `start_marker_close` (Default: `>`) * `end_marker_open` (Default: ``) This allows users to redefine tags completely, e.g., to `[SECTION]` ... `[/SECTION]` or `{{#SECTION}}` ... `{{/SECTION}}`. ## 2. Decision: "Ahead-of-Time" (AOT) Template Compilation Parsing text templates, validating variable references, and checking for cycles is expensive. We will **not** do this during the standard `dctx` runtime. ### The "Baked-In" Default The default template (defined in the ADR) is parsed at **Rust Compile Time** (or hardcoded as a static struct). This ensures `dctx` runs with zero parsing overhead out-of-the-box. ### User Custom Templates Users can edit templates in `~/.config/dctx/templates/`. However, `dctx` does not read these text files directly during snapshot generation. * **Action:** User edits `.dctx_template` file. * **Command:** User runs `dctx template build `. * **Process:** 1. `dctx` parses the text file. 2. Validates syntax and variable references. 3. Serializes the parsed structure into an optimized binary format (e.g., `bincode`). 4. Saves the result to `~/.cache/dctx/templates/user_custom.bin`. * **Runtime:** When `dctx` runs, if configured to use a custom template, it loads this pre-validated binary directly into memory. ## 3. Decision: Two-Pass Rendering Engine The rendering engine operates in two distinct passes to separate Configuration from Data. * **Pass 1 (Config Resolution):** Occurs during the "Template Build" phase. Resolves all `{{VAR}}` placeholders within the `[VARIABLES]` section. * **Pass 2 (Data Injection):** Occurs during runtime. Injects `{{{DATA}}}` into the pre-compiled Partial structures (`[PARTIALS]` section) and assembles the `[LAYOUT]`. ## 4. Template File Structure The file format uses a custom INI-like syntax with three specific sections: 1. **[VARIABLES]:** Key-Value pairs for static strings. 2. **[PARTIALS]:** Definitions for repeated elements (`TREE_ENTRY`, `FILE_BLOCK`). 3. **[LAYOUT]:** The global document structure. ## 5. Available Data Variables (Runtime) These variables are populated by the Rust core: * `{{{node.id}}}`: Optimized incremental ID (e.g., 1, 2, 10). * `{{{node.path}}}`: Relative path. * `{{{node.type_char}}}`: `[D]` or `[F]`. * `{{{node.mod}}}`: Unix timestamp in milliseconds. Available to custom templates. The built-in default template does not print it since 1.0.1, because a timestamp changes on a bare `touch` and breaks the byte-stable prefix of the page; `--tree-stamps=on` selects the built-in stamped template (the 1.0.0 text, `MOD:` and `SIZE:` on every tree line, `MOD` in the instructions). The default entry also leaves out `{{{node.size_part}}}`, since a size changes on every ordinary edit; `{{{node.size}}}` and `{{{node.size_part}}}` stay available to custom templates. * `{{{node.size}}}`: File size in bytes. * `{{{file.lines}}}`: Line count of the file. * `{{{file.content}}}`: Actual file content. 6. TEMPLATE DEFINITION V1: ```text # ============================================================================== # DCTX TEMPLATE DEFINITION V1 # ============================================================================== # This file defines how the LLM context is formatted. # It consists of three sections: [VARIABLES], [PARTIALS], and [LAYOUT]. # # SYNTAX GUIDE: # - {{VAR_NAME}} : Inserts a configuration variable defined in [VARIABLES]. # - {{{DATA_FIELD}}} : Inserts dynamic data from the project (e.g., file content). # # ============================================================================== [VARIABLES] # --- 1. Syntactic Markers (Granular Control) --- # Defines the exact characters used to wrap tags. # Allows handling XML, HTML, or Custom formats safely. start_marker_open = "<" start_marker_close = ">" end_marker_open = "" # --- 2. Semantic Marker Names --- # Defines the keywords used inside the tags. instr_marker = "INSTRUCTIONS" tree_start_marker = "DIRECTORY_TREE" tree_end_marker = "DIRECTORY_TREE" file_start_marker = "FILE_CONTENT_START" file_end_marker = "FILE_CONTENT_END" # --- 3. Attribute Keys --- # Used inside tags to denote properties. attr_id = "ID" attr_path = "PATH" attr_size = "SIZE" attr_lines = "LINES" attr_mod = "MOD" # --- 4. Instructions Block Text --- # This text explains the format to the LLM. It references the variables above # to ensure the instructions always match the actual format used. # Use '\n' for new lines. instructions_text = "1. Manifest: The {{start_marker_open}}{{tree_start_marker}}{{start_marker_close}} section lists all files.\n - Each entry: [TYPE] RELATIVE_PATH ({{attr_id}}:UNIQUE_ID)\n - TYPE is [D] for directory, [F] for file.\n2. Content Access: To read a specific file:\n - Find its UNIQUE_ID from the directory tree.\n - Search for the marker: {{start_marker_open}}{{file_start_marker}} {{attr_id}}=\"UNIQUE_ID\"{{start_marker_close}}\n - The content is between this marker and {{end_marker_open}}{{file_end_marker}} {{attr_id}}=\"UNIQUE_ID\"{{end_marker_close}}" # ============================================================================== # [PARTIALS] # Defines the look of repeated elements (Tree items and Files). # ============================================================================== # --- Tree Entry Partial --- # Context: 'node' object # Available Data: {{{node.type_char}}}, {{{node.path}}}, {{{node.id}}}, {{{node.mod}}}, {{{node.size}}} # The default entry leaves {{{node.mod}}} and {{{node.size_part}}} out (1.0.1); a custom template may add `, {{attr_mod}}:{{{node.mod}}}{{{node.size_part}}}`. [PARTIAL:TREE_ENTRY] {{{node.type_char}}} {{{node.path}}} ({{attr_id}}:{{{node.id}}}) # --- File Block Partial --- # Context: 'file' object # Available Data: {{{file.id}}}, {{{file.path}}}, {{{file.lines}}}, {{{file.size}}}, {{{file.content}}} [PARTIAL:FILE_BLOCK] {{start_marker_open}}{{file_start_marker}} {{attr_id}}="{{{file.id}}}" {{attr_path}}="{{{file.path}}}" {{attr_size}}="{{{file.size}}}" {{attr_lines}}="{{{file.lines}}}"{{start_marker_close}} {{{file.content}}} {{end_marker_open}}{{file_end_marker}} {{attr_id}}="{{{file.id}}}"{{end_marker_close}} # ============================================================================== # [LAYOUT] # The master structure of the final output file. # Note: The Version Header (e.g. [DCTX_SNAPSHOT_V1]) is hardcoded in the binary # and NOT included here. # ============================================================================== [LAYOUT] {{start_marker_open}}{{instr_marker}}{{start_marker_close}} {{instructions_text}} {{end_marker_open}}{{instr_marker}}{{end_marker_close}} {{start_marker_open}}{{tree_start_marker}}{{start_marker_close}} {{{comp.tree}}} {{end_marker_open}}{{tree_end_marker}}{{end_marker_close}} {{{comp.files}}} ``` # ADR-014: Privacy Guarantees & Ignore Semantics **Status:** current — architectural principle retained; historical examples describe their original release. For shipped behavior and limitations, see the [README](../README.md), [testing guide](TESTING.md) and [specification](SPEC.md). Earlier “formally proven” wording refers to historical tests; tests and defense layers do not constitute a formal proof of all implementations. **Date:** 2026-02-02 **Approved:** 2026-02-02 **Implemented:** 2026-02-02 (WO-050 through WO-054) **Deciders:** Operator, AI Assistant **Context:** Phase 10.6 - Safety-Critical Privacy & Performance Audit --- ## Context and Problem Statement Users trust `dctx` with their entire codebases, including sensitive files like `.env`, `.git/`, API keys, credentials, and proprietary source code. Our ignore and omit systems were implemented primarily for output cleanliness and token efficiency, but we have not formally guaranteed that ignored files are **NEVER** read into memory. **Critical Questions:** 1. Are ignored files (`.env`, credentials) ever read into memory? 2. Does the `--debug-ignored` flag compromise privacy? 3. What is the semantic difference between IGNORE and OMIT? 4. Can template variables accidentally trigger file reads on ignored files? 5. Do we recurse into ignored folders (performance impact)? **Risk:** Without formal privacy guarantees, users cannot trust `dctx` with sensitive codebases. A single accidental file read could expose credentials, leak proprietary code, or violate security policies. --- ## Decision Drivers * **Privacy First:** Ignored files must NEVER be read, regardless of flags or configuration * **Performance:** Ignored folders must be skipped entirely (no recursion) * **Semantic Clarity:** IGNORE vs OMIT must have clear, enforced meanings * **Debug Transparency:** Users must be able to verify their ignore rules work correctly * **Template Safety:** Custom templates must not accidentally trigger I/O on ignored files * **Zero Trust:** Assume users handle classified/sensitive information --- ## Considered Options ### Option 1: Status Quo (No Formal Guarantees) * **Pro:** No code changes required * **Pro:** Current behavior is already safe (but undocumented) * **Con:** No formal verification or tests * **Con:** Users cannot trust the system * **Con:** Template variables could be unsafe in the future * **Verdict:** [no] Rejected - Privacy must be provable, not assumed ### Option 2: Full Privacy Audit + Formal Guarantees (SELECTED) * **Pro:** Provable privacy through code analysis and tests * **Pro:** Clear semantic distinction between IGNORE and OMIT * **Pro:** Template variable safety system prevents accidental reads * **Pro:** Performance optimizations (skip ignored folders) * **Pro:** Debug mode that doesn't compromise privacy * **Con:** Requires implementation work (2-3 hours) * **Verdict:** [yes] **SELECTED** - Only acceptable solution for sensitive codebases ### Option 3: Encryption-Based Approach * **Pro:** Could encrypt ignored file contents in memory * **Con:** Massive complexity, performance overhead * **Con:** Doesn't solve the problem (still reading files) * **Verdict:** [no] Rejected - Overengineered, doesn't address root issue --- ## Decision Outcome **Chosen Option:** Option 2 - Full Privacy Audit + Formal Guarantees We will implement a three-tier rule system with formal privacy guarantees: --- ## Rule System Definition | Rule Type | Directory Tree Visibility | File Content Section | Recurse into Folders? | Read File into Memory? | |-----------|---------------------------|----------------------|----------------------|------------------------| | **IGNORE** (default) | [no] Hidden | [no] Hidden | [no] NO (skip entirely) | [no] **NEVER** | | **IGNORE** (`--debug-ignored`) | [yes] Shown with `[IGNORED]` marker | [no] Hidden | [yes] YES (for diagnostics) | [no] **NEVER** | | **OMIT** (always) | [yes] Shown (normal) | [warning] `[Content omitted by pattern rules]` | [yes] YES | [no] **NEVER** | --- ## Semantic Definitions ### IGNORE **Meaning:** "This file/folder does not exist for our purposes." **Use Cases:** - `.git/` - Version control internals - `node_modules/`, `target/`, `__pycache__/` - Build artifacts - `.env`, `.secrets` - Credentials and sensitive configuration - `*.log`, `*.tmp` - Temporary files **Behavior:** - Default: Not visible in tree, not in content, folder not recursed - Debug Mode: Visible in tree with `[IGNORED]` marker, folder recursed, but files never read - Configuration: `.dctxignore` (project) or `~/.config/dctx/ignore` (global) ### OMIT **Meaning:** "This file exists and is relevant to the project structure, but we don't care about its contents." **Use Cases:** - `package-lock.json`, `Cargo.lock` - Lockfiles (structure matters, content doesn't) - `*.svg` - Image files (relevant to project, but binary/verbose) - `go.sum`, `yarn.lock` - Dependency checksums **Behavior:** - Always visible in directory tree (with metadata) - Content section shows: `[Content omitted by pattern rules]` - File is listed but never read into memory ### Debug Mode (`--debug-ignored`) **Purpose:** Allow users to verify their ignore rules are working correctly. **Behavior:** - Temporarily treats IGNORE rules as OMIT rules for visibility - Shows ignored files/folders in directory tree with `[IGNORED]` marker - Recurses into ignored folders to show structure - **CRITICAL:** Files are still NEVER read into memory - Grayed-out metadata: SIZE from `stat()` only, never from content reading - No LINES count (would require reading file) ### SENSITIVE (strict deny, v1) **Meaning:** "This file holds credentials. No dctx command ever reads, hashes, indexes or prints its bytes." **Shapes** (final path component, ASCII case-insensitive; the single list is `dctx_core::filter::is_secret_shaped_name`): - env files: `.env`, `.env.*`, `*.env`, `.envrc` - keys, certificates and keystores: `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.jks`, `*.keystore` - SSH private keys: `id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519`, and those names with a `_`/`-` suffix without a dot (`id_rsa_deploy`); `id_rsa.pub` is not matched - credentials: `credentials`, `credentials.`, `*.credentials.json`, `secrets.` (data = `json`, `yaml`, `yml`, `toml`, `ini`, `xml`); `credentials.py` and `secrets.rs` stay ordinary source - token files: `.netrc`, `_netrc`, `.npmrc`, `.pypirc`, `.pgpass`, `.htpasswd`, `.git-credentials` **Behavior:** - The file stays listed by name (pack tree, map inventory) with its content omitted, and is never read. - Applies whether or not the file is git-tracked, to every surface: `pack` (all view filters, including `--include`, `--ext`, `--hidden` and `--debug-ignored`), every `dctx map` verb (map, find, read, explain, skeleton, grep, neighbors, hubs, path, export; by stable id or by raw path; with or without `--in`). - Enforced in the map policy (`PolicyView::decide`), again before any map read (`Session::read_verified`), in map grep, in the pack scan (`dctx-pack` snapshot) and in the `dctx-map-query` source adapter. - **No override.** v1 has no `--allow-sensitive` flag, and repository or global rule files cannot re-include these shapes. dctx decides by name only; it does not scan contents, so a secret pasted into an ordinary source file is not detected. **Verification:** `crates/dctx/tests/map_sensitive_files.rs`, the unit tests next to `is_secret_shaped_name`, `PolicyView::decide` and the pack scan, and the end-to-end check `/scripts/checks/V1-1.zsh` (a git-tracked fixture with one canary per shape, run against every command). ### `.git` (hard guard, v1) Any path with a `.git` segment, at any depth, is excluded by `PolicyView::decide` before the rule layers are consulted, so `!.git/`, `!.g*/` or `!nested/.git/**` in `.gitignore` or `.dctxignore` cannot re-include it: the map verbs never list or read it, and `Session::read_verified` refuses it too. `pack` excludes it as well (`dctx-pack` snapshot); only `--debug-ignored` still lists it by name, never reading it. Tests: `git_negations_never_list_or_read_git` in `crates/dctx/tests/git_and_symlink_privacy.rs` and in the pack snapshot. ### Symlinks (v1) `dctx::FsSource` never follows a symlink: a symlinked final component is refused before the open, and the open itself uses `O_NOFOLLOW` (raw platform values; crates/dctx has no `libc` dependency), so a symlink swapped in after the stat is refused by the kernel; the opened handle must be a regular file. A symlinked intermediate directory is refused for listings and reads. Tests: `crates/dctx/src/adapters/fs.rs` and `crates/dctx/tests/git_and_symlink_privacy.rs`. ### `DCTX_INDEX_IGNORED=1` This environment switch (dctx-cli `host::project_rules`) makes `pack` and the map verbs ignore every ignore file (global ignore, `.gitignore`, nested `.gitignore`, `.dctxignore`); omit files and the built-in rules still load. It does not touch the SENSITIVE deny, the `.git` guard or the symlink rules above: those do not come from rule files. `/scripts/checks/V1-1.zsh` reruns its canary checks with the switch set. --- ## Privacy Guarantees (Formal) ### Guarantee 1: Ignored Files Never Enter Read Queue [yes] **Assertion:** Files matching ignore rules are excluded at tree construction time (`walker.rs:136-146`) via `should_ignore_item()` check. They never appear in the `DirContextTreeNode` tree, therefore never collected by `collect_file_paths()`, therefore never read by `populate_file_contents_parallel()`. **Verification:** [yes] PROVEN - [yes] Static code analysis completed (WO-052) - [yes] Unit test: `test_collect_file_paths_skips_ignored` - ignored file never in read queue - [yes] Unit test: `test_collect_file_paths_skips_ignored_subtree` - entire subtrees skipped - [yes] Privacy guarantee formally proven through test chain ### Guarantee 2: Ignored Folders Skip Recursion **Assertion:** When a folder matches ignore rules, `walk_recursive()` uses `continue` (walker.rs:146) to skip the item entirely. The function is never called recursively on that folder's children. **Verification:** - Performance benchmark: 500MB `node_modules/` should take < 100ms to skip - Without ignore: Same folder would take 5-10 seconds to scan - Debug mode exception: Recurses but still never reads files ### Guarantee 3: Debug Mode Does Not Compromise Privacy [yes] **Assertion:** When `--debug-ignored` is active, the system recurses into ignored folders and shows them in the tree, but the files are marked with `is_ignored: true` flag. The `populate_file_contents_parallel()` function respects this flag and never calls `fs::read()` on ignored files. **Verification:** [yes] PROVEN - [yes] Test: `test_ignored_files_shown_with_marker` - `.env` appears in tree with [IGNORED] - [yes] Test: `test_ignored_files_never_have_content` - no content blocks for ignored files - [yes] Test: `test_collect_file_paths_skips_ignored` - ignored files never enter read queue - [yes] Privacy preserved even in debug mode (WO-051, WO-052, WO-053) ### Guarantee 4: Template Variables Cannot Trigger Unsafe Reads [yes] **Assertion:** Template variables are classified by I/O requirement: - **Metadata-Only:** `{{{file_id}}}`, `{{{file_path}}}`, `{{{file_size}}}`, `{{{mod}}}` (safe - from `stat()`) - **Content-Requiring:** `{{{lines}}}`, `{{{content_preview}}}` (unsafe - requires `fs::read()`) For ignored/omitted files, content-requiring variables are never resolved due to `!node.is_ignored` guard preventing content block rendering. **Verification:** [yes] PROVEN - [yes] Test: `test_template_variable_safety_for_ignored_files` with 6 comprehensive assertions (WO-054) - [yes] Documentation: Module-level safety documentation in llm_formatter.rs - [yes] Documentation: Template Variable Safety section in DEVELOPER-GUIDE.md - [yes] Multi-layer defense prevents any code path from triggering reads on ignored files --- ## Performance Characteristics ### Ignored Folder Skip (Primary Optimization) **Scenario:** Project with 500MB `node_modules/` (50,000 files) | Mode | Behavior | Time | `fs::read()` Calls | |------|----------|------|-------------------| | Default | Skip entire folder | < 100ms | 0 | | Without ignore | Scan all 50k files | 5-10 sec | 50,000 | | Debug mode | Recurse but don't read | < 500ms | 0 | **Performance Gain:** 50-100x faster for large ignored folders. ### Omit Pattern Performance **Scenario:** Lockfiles in monorepo (20 files, 10MB each) | Mode | Behavior | Time | Memory | |------|----------|------|--------| | Include all | Read all lockfiles | ~200ms | 200MB | | Omit lockfiles | Show in tree, skip content | ~10ms | 2MB | **Performance Gain:** 20x faster, 100x less memory. --- ## Implementation (COMPLETED) ### Phase 1: Data Structure Changes [yes] (WO-050) **Completed:** 2026-02-02 1. [yes] Added `is_ignored: bool` to `DirContextTreeNode` struct (datatypes.rs:15) 2. [yes] Default: `false` (only set to `true` in debug mode) 3. [yes] Propagates to all children of ignored folders in debug mode 4. [yes] All 284 tests passing after change **Code Location:** `crates/dctx-core/src/datatypes.rs:15` ### Phase 2: Walker Logic Enhancement [yes] (WO-051) **Completed:** 2026-02-02 1. [yes] `walk_directory_structure()` and `walk_recursive()` accept `debug_ignored: bool` parameter 2. [yes] Default behavior: Skip ignored items with `continue` (current behavior preserved) 3. [yes] Debug behavior: Recurse into ignored folders, mark all nodes with `is_ignored: true` 4. [yes] Added `mark_subtree_as_ignored()` helper function for recursive flag propagation 5. [yes] Updated CLI main.rs to pass debug flag 6. [yes] All 284 tests passing **Code Locations:** - `crates/dctx-core/src/walker.rs:95-150` - Enhanced walk_recursive() - `crates/dctx-core/src/walker.rs:mark_subtree_as_ignored()` - Helper function - `crates/dctx-cli/src/main.rs` - CLI integration ### Phase 3: Privacy Enforcement in Collection [yes] (WO-052) **Completed:** 2026-02-02 1. [yes] Updated `collect_file_paths()` to respect `is_ignored` flag and skip ignored files 2. [yes] Added `test_collect_file_paths_skips_ignored` - proves ignored files never collected 3. [yes] Added `test_collect_file_paths_skips_ignored_subtree` - proves entire subtrees skipped 4. [yes] Privacy guarantee formally proven through test coverage 5. [yes] All 286 tests passing (284 existing + 2 new privacy tests) **Code Locations:** - `crates/dctx-core/src/walker.rs:180` - Collection filter - `crates/dctx-core/src/walker.rs::test_collect_file_paths_skips_ignored` - Privacy test 1 - `crates/dctx-core/src/walker.rs::test_collect_file_paths_skips_ignored_subtree` - Privacy test 2 ### Phase 4: Formatter Respect for `is_ignored` Flag [yes] (WO-053) **Completed:** 2026-02-02 1. [yes] Directory tree rendering: Append `[IGNORED]` marker to ignored items 2. [yes] Content section: Skip ignored items via `!node.is_ignored` guard (llm_formatter.rs:345) 3. [yes] Diff section: Skip ignored items via `!node.is_ignored` guard (llm_formatter.rs:389) 4. [yes] Added 3 comprehensive unit tests for ignored node handling 5. [yes] All 289 core tests passing 6. [yes] All 5 integration test suites passing **Code Locations:** - `crates/dctx-core/src/llm_formatter.rs:345` - Content block guard - `crates/dctx-core/src/llm_formatter.rs:389` - Diff block guard - `crates/dctx-core/src/llm_formatter.rs::test_ignored_files_shown_with_marker` - `crates/dctx-core/src/llm_formatter.rs::test_ignored_files_never_have_content` - `crates/dctx-core/src/llm_formatter.rs::test_ignored_files_never_in_diff` ### Phase 5: Template Variable Safety System [yes] (WO-054) **Completed:** 2026-02-02 1. [yes] Added comprehensive module-level documentation explaining multi-layer defense strategy 2. [yes] Documented variable classification (metadata-only vs content-requiring) 3. [yes] Added inline safety comments at critical guard locations 4. [yes] Created `test_template_variable_safety_for_ignored_files` with 6 comprehensive assertions 5. [yes] Updated DEVELOPER-GUIDE.md with Template Variable Safety guidelines 6. [yes] All 290 tests passing (289 existing + 1 new) 7. [yes] All 5 integration test suites passing **Code Locations:** - `crates/dctx-core/src/llm_formatter.rs` - Module-level safety documentation - `crates/dctx-core/src/llm_formatter.rs:345` - Safety comment at guard - `crates/dctx-core/src/llm_formatter.rs::test_template_variable_safety_for_ignored_files` - `docs/guides/DEVELOPER-GUIDE.md` - Template Variable Safety section --- ## Consequences ### Positive [yes] **Provable Privacy:** Users can verify ignored files are never read [yes] **Performance Boost:** 50-100x faster for projects with large ignored folders [yes] **Semantic Clarity:** IGNORE vs OMIT distinction is clear and enforced [yes] **Debug Transparency:** Users can verify ignore rules without compromising privacy [yes] **Template Safety:** Custom templates cannot accidentally leak ignored file contents [yes] **Trust:** Enterprise users can confidently use `dctx` on classified codebases ### Neutral [settings] **Implementation Cost:** 2-3 hours of development work [settings] **Test Overhead:** 4 new privacy tests, 2 performance benchmarks [settings] **Documentation:** ADR, README security section, developer guide updates ### Negative [no] **API Change:** `walk_recursive()` signature changes (internal API only) [no] **Binary Size:** +1-2KB for additional logic (negligible) [no] **Complexity:** Template variable classification system adds minor complexity --- ## Compliance & Validation ### Privacy Compliance Checklist [yes] ALL COMPLETE - [yes] Ignored files never appear in `DirContextTreeNode` tree (default mode) - WO-051 - [yes] Ignored folders never recursed (default mode) - WO-051 - [yes] Debug mode shows ignored items but never reads them - WO-052, WO-053 - [yes] `fs::read()` never called on ignored files - Proven via test chain WO-052 - [yes] Template variables respect `is_ignored` flag - WO-054 - [yes] No code path can trigger read on ignored files - Multi-layer defense verified ### Performance Validation Checklist - [ ] Ignored folder skip < 100ms for 50k files - [ ] Scan time unchanged when ignore rules added (vs removed) - [ ] Memory usage proportional to non-ignored files only ### Documentation Checklist (IN PROGRESS - WO-055 through WO-059) - [yes] ADR-014 created and reviewed (WO-055) - [pending] README.md updated with privacy guarantees (WO-057 - PENDING) - [yes] DEVELOPER-GUIDE.md explains implementation (WO-054) - [pending] CLI `--help` documents `--debug-ignored` behavior (WO-056 - PENDING) - [pending] User-facing docs explain IGNORE vs OMIT (WO-057 - PENDING) --- ## Related Decisions * **ADR-008:** Content Omission Pattern System (established omit rules) * **ADR-009:** Binary File Detection and Content Omission (binary classification) * **ADR-001:** System Architecture (centralized state management) * **ADR-011:** Advanced CLI Filters (filter system that respects privacy) --- ## References * Walker implementation: `crates/dctx-core/src/walker.rs` * Ignore rules: `crates/dctx-core/src/ignore.rs` * Omit rules: `crates/dctx-core/src/omit_content.rs` * Formatter: `crates/dctx-core/src/llm_formatter.rs` * Phase 10.6 specification: the archived `PROJECT-DEVELOPMENT-ELABORATION.md` in `docs/LEGACY/` --- ## Implementation Work Orders This ADR was implemented through the following Work Orders: | WO | Date | Subject | Status | |----|------|---------|--------| | **WO-050** | 2026-02-02 | Data Structure Enhancement: Add is_ignored Flag | [yes] COMPLETE | | **WO-051** | 2026-02-02 | Walker Logic Enhancement: Debug Mode with Privacy | [yes] COMPLETE | | **WO-052** | 2026-02-02 | Privacy Enforcement in File Content Reading | [yes] COMPLETE | | **WO-053** | 2026-02-02 | Formatter Enhancement: Respect is_ignored Flag | [yes] COMPLETE | | **WO-054** | 2026-02-02 | Template Variable Safety Classification System | [yes] COMPLETE | | **WO-055** | 2026-02-02 | Creation of ADR-014 (this document) | [yes] COMPLETE | | **WO-056** | TBD | Update CLI help text with privacy guarantees | [pending] PENDING | | **WO-057** | TBD | Update README.md security section | [pending] PENDING | | **WO-058** | TBD | Create privacy test suite (4 tests minimum) | [pending] PENDING | | **WO-059** | TBD | Create performance benchmark | [pending] PENDING | **Current Status:** Core implementation complete. Documentation updates in progress. --- ## Test Coverage Summary **Total Tests:** 290 (as of WO-054) - 284 core tests (existing) - 2 privacy tests (WO-052): Collection layer verification - 3 formatter tests (WO-053): Output layer verification - 1 template safety test (WO-054): Variable resolution verification **Integration Tests:** 5/5 passing (Phase 5 test-integrity.sh) **Privacy Tests:** 1. [yes] `test_collect_file_paths_skips_ignored` - Single ignored file never collected 2. [yes] `test_collect_file_paths_skips_ignored_subtree` - Entire ignored subtree skipped 3. [yes] `test_ignored_files_shown_with_marker` - Debug mode shows [IGNORED] marker 4. [yes] `test_ignored_files_never_have_content` - No content blocks for ignored files 5. [yes] `test_ignored_files_never_in_diff` - No diff blocks for ignored files 6. [yes] `test_template_variable_safety_for_ignored_files` - Template safety with 6 assertions **Privacy Guarantee Status:** [yes] **FORMALLY PROVEN** through test chain and multi-layer defense # ADR-018: Language Coverage **Status:** superseded — historical design and implementation record. The original 13-family scope below is superseded by the [current language registry table](../README.md#language-tiers); confidence and completion principles remain relevant. ## Context ### The Problem Map facts need explicit coverage and completion claims across source/configuration languages; precision is separate from edge confidence (`crates/dctx-map-model/src/domain/precision.rs`). ### Root Cause Analysis Structural extraction is not a full grammar claim, and incomplete extraction must not silently become complete facts (`crates/dctx-map-model/src/domain/precision.rs`, `crates/dctx-map-parse/src/adapters/mod.rs`). ## Decision Use pure structural extraction for 13 families: Rust, JavaScript/TypeScript, Markdown, Python, Go, Java, C/C++, configuration (JSON/TOML/YAML), C#, Kotlin, Ruby, PHP and Swift (`crates/dctx/src/index/extract.rs`, `docs/CRATE-MAP.md`). The facade's default profile uses hand-written extraction, including line-oriented Rust and the first-party Markdown extractor. **Qualification:** `dctx-lex-rust` itself uses `syn`; it is optional behind facade `syntax-rust`, so “13 hand-written lexers” is not a claim about every lexer crate or map-parse Rust implementation (`crates/dctx/src/index/extract.rs`, `crates/dctx/Cargo.toml`, `crates/dctx-lex-rust/src/lib.rs`). Keep one shared facade dispatch and fact-to-symbol conversion in `crates/dctx/src/index/lex_dispatch.rs`; Rust and Markdown retain specialized entry paths in `crates/dctx/src/index/extract.rs`. Carry coverage (`syntax`, `structural`, `opaque`), completion (`complete`, `partial`, `refused`) and bounded parser identity separately from confidence (`crates/dctx-map-model/src/domain/precision.rs`). ## Implementation ### Phase 1: Pure Lexers and Facade Projection The shared dispatch converts nodes without reading source or retaining bodies. New language branches expose only complete extraction; JavaScript/TypeScript preserve their existing partial-fact projection (`crates/dctx/src/index/lex_dispatch.rs`). The facade rejects NUL/non-UTF-8 symbol extraction and assigns stable ids and containment after extraction (`crates/dctx/src/index/extract.rs`). ### Phase 2: Map-parse Adapters `PureParser` dispatches the language adapters over caller-provided bytes; partial/diagnostic extraction is refused as `ParseError::Syntax`, and unknown languages have a module-only fallback (`crates/dctx-map-parse/src/adapters/mod.rs`). Shared fact assembly records file precision and finalizes source-ordered facts with duplicate-id handling (`crates/dctx-map-parse/src/adapters/facts.rs`). ### Phase 3: Store Invariants Gate The parser gate checks file ownership, unique/kind-correct ids, source-bounded spans, valid confidence/kind combinations, existing edge endpoints and containment reachability. It also simulates query insertion of Place/Package nodes to catch duplicate ids (`crates/dctx-map-parse/tests/lexers.rs`, `crates/dctx-map-parse/tests/fuzz_all.rs`). ### Phase 4: Fuzz Gate Seeded bounded property tests exercise arbitrary bytes, Unicode, malformed inputs, deterministic results, successful-result store invariants and fixture prefixes without executing source (`crates/dctx-map-parse/tests/fuzz_all.rs`). ## Results The gate source defines successful fixture controls as well as refusal/robustness cases; this record asserts test obligations, not a new passing execution (`crates/dctx-map-parse/tests/lexers.rs`, `crates/dctx-map-parse/tests/fuzz_all.rs`). ## Trade-offs ### Benefits Structural facts can be produced without a default tree-sitter runtime, with explicit precision and conservative abstention (`crates/dctx-map-parse/src/adapters/mod.rs`, `crates/dctx/src/index/lex_dispatch.rs`). ### Costs The facade's structural Rust profile and optional syn path differ; the shared facade dispatch also deliberately differs from PureParser on JavaScript partial facts (`crates/dctx/src/index/extract.rs`, `crates/dctx/src/index/lex_dispatch.rs`, `crates/dctx-map-parse/src/adapters/mod.rs`). ## Alternatives Considered The earlier spec proposed tree-sitter as the parser dependency. Current adapters retain it only behind `syntax-tree-sitter` as an optional oracle; languages without an included grammar use pure adapters even in that oracle (`docs/SPEC-MAP-MODE.md`, `crates/dctx-map-parse/src/adapters/mod.rs`). ## References Inventory: `docs/CRATE-MAP.md`; facade: `crates/dctx/src/index/lex_dispatch.rs`; adapters: `crates/dctx-map-parse/src/adapters/mod.rs`; robustness: `crates/dctx-map-parse/tests/fuzz_all.rs`. ## Lessons Learned Language family count, structural coverage, grammar completeness and edge confidence are distinct claims; the Rust implementation qualification must remain visible (`docs/CRATE-MAP.md`, `crates/dctx-map-model/src/domain/precision.rs`, `crates/dctx-lex-rust/src/lib.rs`). ## Future Work Keep tree-sitter optional and preserve precision/refusal and store-invariant gates when extending adapters; optional oracle coverage is limited to its included grammars (`crates/dctx-map-parse/src/adapters/mod.rs`, `crates/dctx-map-parse/tests/fuzz_all.rs`). # dctx measurement: grep plus file reads first The baseline for choosing dctx is **grep plus reading files**. Count the whole agent session before claiming a cost saving. Output bytes and estimated output tokens measure only the returned context; they exclude startup instructions, tool descriptions, conversation replay, model output and provider cache effects. ## Grep plus file reads The [11 November whole-session benchmark](BENCHMARK-20261111.md) measured grep plus reads against dctx CLI: CLI median total tokens -5.01 %; the pre-registered 25 % savings rule was not met. Official strict citation recall medians (A/B/C): 10.10 % / 14.46 % / 13.41 %; diagnostic file-level recall: 53.77 % / 71.70 % / 76.42 %. The claim is accuracy and bounded context, not token savings. On this corpus and model dctx did not save 25 % tokens. The linked report gives median [min, max], methods and limitations; corpus and raw answers are private. ## Secondary historical evidence: other-tool protocols Everything below retains the October/November research record, including its older limitations and plans. These other-tool comparisons are historical notes, not the product's headline baseline or a recommendation between tools. All "tokens" in these tables mean estimated **tool stdout tokens**, calculated as `ceil(stdout_bytes / 3.5)`, never whole-session tokens. Task scores are fact coverage in raw outputs without a model, not agent completion rates. One command, same host, same corpora, same CPU set, no network, pinned versions. Raw aggregate, headline tables and the harness are in [`research/bench-3way-20261030/`](research/bench-3way-20261030/); the current goals are in the [specification](SPEC.md). Where another tool wins, the tables say so. - **dctx**: `main` at `ac8408c` (the following commit only changes `CHANGELOG.md`), release build, sha256 `82bd48760932305748a00d2b32901c667af948f602822b9816cc5c545de7ebbc`. Baseline for "before" columns: `main` at `4660f6d`, the state before this night's work. - **Trail-Code** `@trailhq/trail-code` 0.28.0 from npm, `trail build .` (no `--deep`, no `--lsp`). - **graphify** `graphifyy` 0.9.97 from PyPI, LLM-free code path only (`extract --code-only`, `GRAPHIFY_BACKEND=none`). Its LLM pass over docs, PDFs and images was **not** run, and nothing here measures it. ## Historical three-way summary | Area | Result | |---|---| | Task-level questions, October protocol (70 questions) | **Run 7: dctx 140 of 140, Trail-Code 122, graphify 96**, with dctx using 29.3k tokens against Trail-Code's 88.9k and graphify's 197k. See "Run 7" below. | | Callers (depth 1) against a tool-independent gold set, 80 targets on 4 corpora | **Run 5: dctx P 0.995 / R 0.851 (first page), R 0.968 following 5 pages.** Run 1 below: dctx P 0.993 / R 0.461 (first page), P 0.995 / R 0.706 following up to 5 pages. Trail-Code P 0.986 / R 0.436, graphify P 0.989 / R 0.196. Per corpus, Trail-Code wins ripgrep and trailcode, and dctx wins flask and pocketbase. Before tonight dctx recall was 0. | | Cold index | **dctx fastest on all 6 corpora**: 0.16–1.16 s against 1.17–58.3 s for Trail-Code and 4.5–59 s for graphify. Peak RSS 19–90 MB against 121–1,020 MB and 74–394 MB. | | Warm queries (median of 5, including process start) | **dctx fastest** on search, callers and skeleton everywhere: 44–226 ms against 0.98–1.9 s for Trail-Code and 0.38–1.4 s for graphify. graphify's overview is a 7 ms read of a pre-written file. | | Answer size | dctx `map hubs` gives the smallest overview on 4 of 6 corpora (Trail-Code on trailcode and docs) (30–652 tokens; Trail-Code 18–2,538; graphify 3,827–11,591). graphify gives the smallest callers and skeleton answers. dctx's skeleton is the largest of the three on ripgrep (1,784 tokens). Before tonight dctx's only overview was a 0.45–2.6 M-token `pack`. | | Cache-friendliness | dctx and Trail-Code tie. Both are byte-identical across runs, and after an unrelated edit only the overview changes. graphify changed find, skeleton and overview after `update`, and 1 of 6 ripgrep queries was not deterministic. | | Network | dctx and graphify made 0 socket attempts in every variant. Trail-Code made 49 blocked connect attempts when `DO_NOT_TRACK` is unset, and 0 with it set. | | Language coverage, mixed corpus (10 languages) | **Symbols: dctx 10 of 10, Trail-Code 7, graphify 5.** **Call edges, run 3: dctx 10 of 10, Trail-Code 7, graphify 5** (run 1: dctx 0). dctx's new outline tier is symbols only, labelled `guess`. Terraform and SQL get symbols only from dctx. | | Plain-text docs (.md/.rst/.txt/.adoc corpus) | dctx indexes the corpus into headed sections (0.18 s). graphify's code-only mode produced no index, and Trail-Code indexes no doc nodes. | | Privacy canary (git-tracked `.env` files) | Run 3: **clean for all three tools** after sensitive-file read protection landed. In run 1, `pack` had stopped printing the canary, but explicit `dctx map read m:.env` still returned the file. Trail-Code and graphify leaked nothing in that run. | ## Run 7: 140 of 140 (main `53f8b6b`, 31 October, 06:20 UTC) New since run 6: - unresolved-call output: `neighbors --dir out` also lists the calls the index cannot resolve, as `calls:out:?` records after the resolved callees. These are receiver methods, builtins and external package calls. - dotted config keys: dotted config key matching (`dotted_key`), not yet wired into `find`. - PowerShell edges: PowerShell symbols and command-position call edges. All landed checks passed together on the Linux benchmark host before the run. Raw results are in `research/bench-3way-20261030/tasks/results/run5-53f8b6b/` and `research/bench-3way-20261030/results/run7-53f8b6b/`. **Task-level protocol** (70 questions, 354 gold facts; generator, mapping and scorer unchanged): | Tool | Points /140 | Gold facts /354 | Tokens | Facts per 1k tokens | |---|---|---|---|---| | dctx `53f8b6b` | **140** (run 6: 136) | **353** (342) | **29,340** | **12.0** | | Trail-Code 0.28.0 | 122 | 312 | 88,923 | 3.51 | | graphify 0.9.97, code-only | 96 | 238 | 197,203 | 1.21 | dctx scores every point on all ten question types. Callees went from 10 to 14 of 14 (37 of 38 facts). It uses a third of Trail-Code's tokens and a seventh of graphify's. **Three-way run 7**: callers P / R on the first page 0.995 / 0.851 (all pages 0.968), the same as run 6. The language coverage table is unchanged at 10 of 10 with symbols and 9 of 10 with call edges; shell is still `n`. Its per-language edge counts rise (for example Scala 1 to 8) because the probe counts every `calls` record, and the new unresolved-call output includes the `calls:out:?` names. A count above zero says nothing new about resolved edges, so this run does not claim more resolved edges. ## Run 6 (main `82ec474`, 31 October, 02:04 UTC) New since run 5: - declaration-definition pairing: a declaration-only symbol (`.mli`, C/C++ header, `.d.ts`) answers neighbors for its paired definition. - Erlang support: Erlang (not in the mixed corpus). - export-list extraction and outgoing-call extraction: `export_list` and `out_calls`, which are not yet wired into answers. All landed checks plus these four passed together on the Linux benchmark host before the run. Raw results are in `research/bench-3way-20261030/results/run6-82ec474/` and `research/bench-3way-20261030/tasks/results/run4-82ec474/`. - Call-edge coverage on the mixed corpus: **9 of 10** (run 5: 8). OCaml now has edges through the `.mli` pairing. Shell still has none, because the probe samples bats `@test` blocks that call only external commands. Trail-Code has 7 and graphify 5. - Callers P / R, first page: 0.995 / 0.851, unchanged (all pages 0.968). - Task protocol: **136 / 140**, unchanged. Trail-Code has 122 and graphify 96. The 4 lost points are still callees questions; the next unresolved-call output improvement wires `out_calls` into neighbors. ## Latest: run 5 and task-level re-run 3 (main `a906884`, 30 October, 16:39 and 17:05 UTC) dctx `a906884` adds four improvements on top of run 4. Caller-diversity improvements spread callers over files, makes bare calls skip methods, and ranks data-file keys below code. Declaration ranking puts exported declarations first in outlines, gives read sites for config keys, adds line numbers to find, and ranks exact-word concepts first. Caller paging orders callers by call-site count and fits pages to the budget. Language outline improvements add deeper Scala, Zig, Lua, Elixir and OCaml symbols. All 36 landed checks passed together on the Linux benchmark host before the run. The binary's sha256 starts with `76d8e9b59821`. Raw results are in `research/bench-3way-20261030/results/run5-a906884/` and `research/bench-3way-20261030/tasks/results/run3-a906884/`. **Task-level protocol** (70 questions, 354 gold facts; generator, mapping and scorer unchanged): | Tool | Points /140 | Gold facts /354 | Tokens | Facts per 1k tokens | |---|---|---|---|---| | dctx `a906884` | **136** (re-run 2: 102) | **342** (243) | **28,472** | **12.0** | | Trail-Code 0.28.0 | 122 | 312 | 88,923 | 3.51 | | graphify 0.9.97, code-only | 96 | 238 | 197,203 | 1.21 | **dctx now wins the task-level test.** It scores 14 points more than Trail-Code with a third of Trail-Code's tokens. By question type, out of 14: | Type | dctx | Trail-Code | graphify | |---|---|---|---| | definition and callers | **14** | 10 | 10 | | impact | **14** | 13 | 12 | | outline | **14** | **14** | 12 | | config key | **14** | **14** | 6 | | exports | **14** | **14** | **14** | | source | **14** | 12 | 0 | | callees | **10** | 8 | 8 | | overview | **14** | 13 | 11 | | collision | **14** | 12 | 13 | | concept | **14** | 12 | 10 | dctx leads or ties on every type. The 4 points it still loses are all callees questions: ripgrep, pocketbase, django and core lose 1 each. In the three public corpora every missing fact is a call that the index could not resolve: a receiver method (`line_terminator`, `lookup_allowed`), a builtin (`callable`) or an external package (`Validate`). The core rows are sanitized. Unresolved-call reporting exposes these calls. **Three-way run 5** (the same harness as runs 1-4): | Callers P / R (first page) | Run 4 | Run 5 | Trail-Code | graphify | |---|---|---|---|---| | flask | 1.000 / 0.977 | 1.000 / 0.977 | 0.962 / 0.328 | 0.933 / 0.195 | | ripgrep | 0.990 / 0.527 | 0.990 / 0.801 | 0.987 / 0.327 | 1.000 / 0.032 | | pocketbase | 1.000 / 0.815 | 1.000 / 0.842 | 1.000 / 0.099 | 1.000 / 0.383 | | trailcode | 0.991 / 0.738 | 0.992 / 0.852 | 0.989 / **0.902** | 1.000 / 0.215 | | all | 0.995 / 0.725 | **0.995 / 0.851** | 0.986 / 0.436 | 0.989 / 0.196 | Following up to 5 pages, dctx reaches P 0.996 / R 0.968 (run 4: 0.982; the site-count order moves some callers past page 5). Trail-Code still wins the trailcode corpus on page 1. The rest of run 5, against the same Trail-Code and graphify runs: - Cold index: dctx 0.13-1.09 s, Trail-Code 1.42-55.5 s, graphify 4.3-61.5 s. - Peak memory: dctx 19-90 MB, Trail-Code 121-1,015 MB, graphify 74-393 MB. - Warm search, callers and skeleton: dctx 43-195 ms, Trail-Code 0.97-2.0 s, graphify 0.41-2.1 s. - No tool leaked the canary. - Network: dctx and graphify made 0 attempts. Trail-Code made 1 blocked connect when `DO_NOT_TRACK` was unset. Call-edge coverage on the mixed corpus is **8 of 10** by the probe; Trail-Code has 7 and graphify 5. The probe samples the first 25 symbols of the six largest files per language. It now follows every skeleton page, so its symbol counts are comparable with Trail-Code's full listing. Two languages miss for reasons outside the call resolver: - OCaml: the first 25 symbols all come from `cmdliner.mli`, an interface file with no bodies. On `cmdliner_arg.ml` itself, `str_of_pp` lists 3 callers with their call lines. Declaration-definition pairing makes an interface declaration answer for its definition. - Shell: the first 25 symbols are bats `@test` blocks in `test/bats.bats`, which call external commands only. ## Task-level questions: the October protocol, re-run on 30 October This is the same protocol as October: 70 questions over seven corpora, 354 gold facts, and October's generator and scorer. It uses no model, and an answer scores when the tool's raw output contains the gold facts. Commands, question mappings and deviations are in `research/bench-3way-20261030/tasks/README.md`. | Tool | Points /140 | Gold facts /354 | Tokens | Facts per 1k tokens | |---|---|---|---|---| | Trail-Code 0.28.0 | **122** (October: 122) | **312** (312) | 88,923 | 3.51 | | graphify 0.9.97, code-only | 96 | 238 | 197,203 | 1.21 | | dctx `de06a3d`, October mapping | 77 (October: 69) | 195 (169) | **25,929** (500,005) | **7.52** | **Trail-Code still wins the task-level test.** dctx gained 8 points and needs a fifth of October's tokens, because its overview question now uses `map hubs` instead of the unbounded legacy tree. dctx's answers are the densest: 7.5 facts per 1,000 tokens against Trail-Code's 3.5. Where dctx still loses: - Caller facts need the call line, and `neighbors` returns the calling function's span. - Config-key and concept questions score 0 under the October mapping. - A supplementary run that uses the verbs added since October reached 96 points (`map grep` for config keys, `map skeleton` for outlines). It is not the October protocol, so it is not counted above. ### Task-level re-run 2 (dctx `5e1b12b`, 30 October, 13:12 UTC) dctx `5e1b12b` adds call-site lines on caller records (call-site lines), the config-key literal fallback (config-key fallback) and multi-word concept ranking (concept ranking). Protocol, mapping and scorer are unchanged. The headline is in `research/bench-3way-20261030/tasks/results/run2-5e1b12b/`. | Tool | Points /140 | Gold facts /354 | Tokens | Facts per 1k tokens | |---|---|---|---|---| | Trail-Code 0.28.0 | **122** | **312** | 88,923 | 3.51 | | dctx `5e1b12b` | **102** (run 1: 77) | 243 (run 1: 195) | **28,742** | **8.45** | | graphify 0.9.97, code-only | 96 | 238 | 197,203 | 1.21 | By question type, out of 14: | Type | dctx | Trail-Code | graphify | |---|---|---|---| | definition and callers | **12** | 10 | 10 | | impact | **14** | 13 | 12 | | source | **14** | 12 | 0 | | callees | **10** | 8 | 8 | | overview | **14** | 13 | 11 | | collision | 10 | 12 | **13** | | outline | 11 | **14** | 12 | | exports | 8 | **14** | **14** | | config key | 7 | **14** | 6 | | concept | 2 | **12** | 10 | dctx now leads on five types and comes second overall, ahead of graphify. Trail-Code still wins outline, exports, config key and concept questions, and is 20 points ahead in total. ## Run 4: callers recall wave (main `de06a3d`, 30 October, 09:17 UTC) The dctx binary's sha256 is `0a41481ffc6f9ecd5713be5af561bef9f1c13f980bfa69748d84540520b4086e`. New since run 3: - compact neighbor records `42a3364`: compact neighbor records, so a page carries about 40 callers. - macro-argument calls `2812e28`: Rust calls inside macro arguments. - receiver calls `baebc3a`: receiver calls resolve to a lone method, and self-edges are listed in both directions. - brace, indent and ML outline improvements `fff4f82`, `37db6a0`, `aa681ea`: deeper outline symbols. - cache ceilings `de06a3d`: per-root cache ceilings of 768 MiB. All 28 checks passed together before the run. Raw results are in `research/bench-3way-20261030/results/run4-de06a3d/`. | Callers P / R (first page) | Run 3 | Run 4 | Trail-Code | graphify | |---|---|---|---|---| | flask | 1.000 / 0.836 | 1.000 / 0.977 | 0.962 / 0.328 | 0.933 / 0.195 | | ripgrep | 0.981 / 0.246 | 0.990 / 0.527 | 0.987 / 0.327 | 1.000 / 0.032 | | pocketbase | 1.000 / 0.667 | 1.000 / 0.815 | 1.000 / 0.099 | 1.000 / 0.383 | | trailcode | 0.983 / 0.332 | 0.991 / 0.738 | **0.989 / 0.902** | 1.000 / 0.215 | | all | 0.993 / 0.461 | **0.995 / 0.725** | 0.986 / 0.436 | 0.989 / 0.196 | Following up to 5 pages, dctx reaches P 0.996 / R 0.982. Call-edge coverage on the mixed corpus is **9 of 10** in this run. The brace outlines brace rewrite cost Zig its call edges on real code (the fixture still passes), which Zig call-edge repair is fixing. Trail-Code has 7 of 10 and graphify 5 of 10. The coverage table's symbol counts come from bounded `map map` pages. They are therefore not comparable with Trail-Code's full graph counts. ## Run 3: all outline families with call edges, `.env` leak closed (main `9c578fa`, 30 October, 08:02 UTC) The dctx binary's sha256 is `72c6a31f0ee807ddd8840c7d8b85c9d1652dcb1001b948fec9de8eabaf277d6d`. New since run 2: - sensitive-file read protection `45a2c06`: map mode never reads env-shaped files. - ML and do/end call edges `df6ab96`: Lua, Elixir, Julia, R, OCaml and Haskell calls. - Scala call edges `9c578fa`: Scala spans and calls. - parser cache invalidation `8ac04e4`: parser id bump, so caches from before call edges are rebuilt. All 20 focused checks passed together on the Linux benchmark host before the run. Raw results are in `research/bench-3way-20261030/results/run3-9c578fa/`. | | Run 1 | Run 2 | Run 3 | |---|---|---|---| | dctx: languages with ≥1 call edge (mixed corpus of 10) | 0 | 6 | **10** | | Trail-Code | 7 | 7 | 7 | | graphify | 5 | 5 | 5 | | dctx: canary from a git-tracked `.env` in any output | yes (`map read`) | yes (`map read`) | **no** | Callers precision and recall on the gold corpora are unchanged (0.993 / 0.461). Cold index stays at 0.13–1.31 s. **Still behind:** - **Symbol depth in the outline tier:** on the mixed corpus's 6 largest files per language, dctx finds 5–25 symbols per language. Trail-Code finds 83–2,559, because its tree-sitter grammars see every member. - **Callers recall on ripgrep and trailcode:** 0.25 and 0.33 against Trail-Code's 0.33 and 0.90. ## Run 2: call edges for the outline tier (main `99da638`, 30 October, 07:24 UTC) Same harness, corpora and tool versions. The dctx binary's sha256 is `81b35b3eb5112921c4f773b2682c247ec667bfc3487ce0670aa5e3ec5a372d14`. The new commits are brace-family call edges (`8859210`, brace family) and infrastructure call edges (`99da638`, infra family). Raw results are in `research/bench-3way-20261030/results/run2-99da638/`. | Mixed corpus, ≥1 call edge | Run 1 | Run 2 | |---|---|---| | dctx | 0 of 10 | **6 of 10** (Dart, Zig, Solidity, Terraform, SQL, shell) | | Trail-Code | 7 of 10 | 7 of 10 (no Terraform, SQL or shell) | | graphify | 5 of 10 | 5 of 10 | dctx is the only tool with call edges for Terraform and SQL. Scala still has none on real code, although the fixture passes; that is a follow-up. Lua, Elixir and OCaml call edges are still being implemented. Cold index (0.13–1.06 s), callers precision and recall, and the canary result are unchanged from run 1. The `map read m:.env` leak remains until sensitive-file read protection lands. ## Tables (run 1) ### Cold index (median wall s, peak RSS of the largest process, index size) | corpus | dctx | Trail-Code | graphify | |---|---|---|---| | flask (Python) | 0.16 s, 19 MB, 1.1 MB | 4.17 s, 225 MB, 4.4 MB | 8.13 s, 102 MB, 4.5 MB | | ripgrep (Rust) | 0.54 s, 25 MB, 2.2 MB | 3.01 s, 303 MB, 8.4 MB | 10.45 s, 93 MB, 8.6 MB | | pocketbase (Go+JS) | 0.91 s, 63 MB, 9.9 MB | 50.63 s, 987 MB, 41.8 MB | 58.96 s, 243 MB, 26.3 MB | | trailcode (TS) | 1.16 s, 90 MB, 14.8 MB | 58.34 s, 1,020 MB, 41.1 MB | 44.32 s, 394 MB, 11.9 MB | | mixed (10 langs) | 0.24 s, 74 MB, 2.8 MB | 3.84 s, 470 MB, 12.8 MB | 4.46 s, 74 MB, 2.2 MB | | docs | 0.18 s, 74 MB, 1.4 MB | 1.17 s, 121 MB, 0.0 MB | failed: no index | ### Callers accuracy (micro precision / recall, depth 1) | corpus | dctx before (4660f6d) | dctx now | Trail-Code | graphify | |---|---|---|---|---| | flask | – / 0.000 | 1.000 / 0.836 | 0.962 / 0.328 | 0.933 / 0.195 | | ripgrep | – / 0.000 | 0.981 / 0.246 | 0.987 / 0.327 | 1.000 / 0.032 | | pocketbase | – / 0.000 | 1.000 / 0.667 | 1.000 / 0.099 | 1.000 / 0.383 | | trailcode | – / 0.000 | 0.983 / 0.332 | 0.989 / 0.902 | 1.000 / 0.215 | | all | – / 0.000 | **0.993 / 0.461** | 0.986 / 0.436 | 0.989 / 0.196 | ### Warm latency and answer size (median ms, estimated tokens) | corpus | query | dctx | Trail-Code | graphify | |---|---|---|---|---| | flask | search | 81 ms, 218 | 1,066 ms, 262 | 564 ms, 1,845 | | flask | callers | 47 ms, 479 | 988 ms, 136 | 381 ms, 32 | | flask | skeleton | 44 ms, 866 | 991 ms, 852 | 514 ms, 474 | | flask | overview | 45 ms, 491 | 1,009 ms, 1,122 | 7 ms, 5,930 | | pocketbase | search | 213 ms, 259 | 1,573 ms, 358 | 1,393 ms, 97 (exit 3) | | pocketbase | callers | 214 ms, 464 | 1,195 ms, 175 | 777 ms, 24 | | pocketbase | overview | 226 ms, 652 | 1,232 ms, 1,514 | 8 ms, 11,591 | | trailcode | callers | 200 ms, 472 | 1,180 ms, 1,064 | 715 ms, 196 | | trailcode | overview | 195 ms, 500 | 1,159 ms, 499 | 7 ms, 10,076 | All corpora and the edit-stability, network and coverage tables are in [`research/bench-3way-20261030/results/headline.md`](research/bench-3way-20261030/results/headline.md). ## Method - Host: a Linux benchmark host (Debian 13, Xeon E5-2680 v2), shared with other jobs. Load was 3.2 at the start, so absolute latencies are noisy. Every measured command ran as `nice -n 10 taskset -c 24-31 unshare -Urn env -i …`, with no network, scratch HOME and caches, and `DO_NOT_TRACK=1`. One heavy process ran at a time. The network audit is a ptrace socket tracer, because strace is not installed. - Corpora are pinned by SHA in `research/bench-3way-20261030/corpora-shas.json`: flask 3.1.3, ripgrep 15.2.0, pocketbase v0.40.5, Trail-Code at the 0.28.0 release commit, a mixed corpus of one public repo for each of 10 languages, and a docs corpus built from python/devguide, rust-lang/book and asciidoctor. - Tokens are `ceil(stdout_bytes / 3.5)` for every tool. That is an estimate, not a tokenizer. - Cold runs use 3 repetitions, except 1 for any tool whose first run took more than 30 s (Trail-Code and graphify on pocketbase and trailcode). Warm runs take the median of 5 after one discarded warm-up. - The callers gold set is the regex oracle of the October protocol (`goldlib.py`) on 20 seeded targets per corpus. A hit is true when its span contains a gold call site. - Query mapping: dctx `map find` / `map neighbors --dir in --edge calls` / `map skeleton` / `map hubs`. Trail-Code `ask` / `callers` / `skeleton` / `map`. graphify `query` / `affected --relation calls` / `explain ` / `GRAPH_REPORT.md`. ## Not claimed These exclusions apply to the historical tool-output protocols below the whole-session summary above. - Whole-session cost or task-level answer quality from these historical protocols. Historical fact scores describe raw tool outputs only; the [11 November study](BENCHMARK-20261111.md) measures whole sessions with a frozen model. - Anything about graphify's LLM semantic graph, or Trail-Code's learnings and LSP edges. - SWE-bench scores or agent-run numbers from these historical tool-output protocols. - Equal language depth. dctx's 25 new formats are outline tier: symbols, not call edges. ## Changes included in the October baseline Call and import edges (`19e90a1`), byte-stable answers (`ce18608`), `.env` omission in pack (`6d4deec`), outline symbols for 25 formats and plain-text sections (`9c61ac9`, `e0821e3`, `839bd45`, `a32dad3`), neighbors depth 4 (`0de5ce1`), `hubs` (`6bc0cbc`), `grep` (`5691234`), `skeleton` (`2243c38`), `path` (`670e9e3`), `export` (`ac8408c`) and a 1 GiB source ceiling (`5d26781`). Each feature's focused check, and then all 15 checks together on `ac8408c`, passed on the Linux benchmark host before the benchmark ran. ## Next 1. sensitive-file read protection: map mode must never serve env-shaped files. This is the remaining privacy leak. 2. Call edges for the outline tier, to close the 0-of-10 call-edge coverage on the mixed corpus. 3. Recall on ripgrep and trailcode (0.25 and 0.33 against Trail-Code's 0.33 and 0.90): method calls through receivers and re-exports. 4. Re-run the 70-question task protocol with a frozen model. ## Independent benchmark, 31.10.2026, run uncapped on the Linux benchmark host Seeded selection of 3 repos the tools never saw (zoxide, requests, gin), gold from language servers and repo history, published regardless of outcome. Tasks: dctx 22/28 points, 31/36 facts, 6.85 facts per 1k tokens (Trail-Code 19/28, graphify 14/28). Callers against LSP gold, first page: dctx P 0.730 / R 0.341, Trail-Code P 0.731 / R 0.313, graphify P 0.920 / R 0.264. Honest read: dctx leads on task answers and token efficiency; caller recall on unseen repos is far below the in-house corpus (0.851), so the caller floors above hold only for the curated corpora. Full table and raw JSON: `docs/research/bench-independent/results/20261031T191225Z/`. # CLI exit codes `dctx map`, `dctx pack`, `dctx context`, `dctx doctor`, `dctx rpc`, `dctx languages`, `dctx cache`, `dctx template`, a bare `dctx` without a terminal, an unknown command and a non-UTF-8 argument follow one contract: Pack and map use the current directory unless a project root is specified, including a directory named `fixtures`; paths are relative to that root. `dctx read` is an alias for `dctx map read`, with the same flags and exit codes. | Code | Meaning | Examples | |---|---|---| | 0 | ok: the command answered | a `find` page, including one with no hits; `--help` | | 1 | no result: the command ran, but the named target or input has no answer | `map read m:nope.py` (an id not in the index); `map read logo.png` (a binary file); `pack` of a directory with no packable file | | 2 | usage: the arguments are wrong | an unknown command or flag; a missing target (`dctx context` with no TARGET); `--depth 9`; an empty `find` query; a stale `--cursor`; `m:../outside`; a non-UTF-8 argument; `cache purge` without `--root`/`--all` or `--yes`; a template that does not compile; a bare `dctx` whose stdin or stdout is not a terminal | | 3 | index error: the place, source, cache or index could not be opened, read, built or written | `--place /no/such/dir`; a corrupt or busy cache; a source over `DCTX_MAX_SOURCE_BYTES`; an `--output` file that cannot be written; `template build /no/such/file` (the message names the path) | Every failure prints two lines on stderr: `[no] Error: ` (prefixed with the command, as `map: …`), then `hint: `. No input should reach a Rust panic; `crates/dctx-cli/tests/cli_errors.rs` and `/scripts/checks/V1-5.zsh` run twelve bad inputs and assert the code, the message, the hint and the absence of `panicked`. ## Details - An id the index does not hold is a facade outcome (`gone`), not an error. `dctx map` prints the `gone` page on stdout, then exits 1 with the hint. - An empty `find` or `grep` page is an answer and exits 0. Exit 1 is for a named target that is not there. - A binary target is detected before the scan: a NUL byte in the first 8 KiB of the file named by `map`, `skeleton`, `explain` or `read` (path or `m:` id). `neighbors` and `path` still accept such a module, since source files can import it. - `dctx pack` exits 1 only when no view filter is set (`--ext`, `--include`, `--exclude`, `--binary`, `--empty`, `--non-empty`, `--large`, `--small`, `--hidden`, `--debug-ignored`). A filter that matches nothing still prints an empty page and exits 0. The page (stdout) and the `pack bytes=…` status line (stderr) are printed before the exit-1 message. `pack` exit 3 covers source, scan, render and output failures. - A reader that closes stdout early (`dctx pack . | head -1`) ends the run with exit 0 and no message, as `cat` does; every other failure keeps its code. - `dctx pack --for ` exits 1 when no name in TEXT matched the index (the page is printed first), 2 for a bad flag or a `--budget` outside 100..100000 (or `--budget` without `--for`), and 3 when PATH is not a directory or the index fails. - A facade refusal of the query (`InvalidRequest`, `BudgetTooSmall`, `StaleContinuation`, `Stale`, `UnsupportedCapability`, `UnsupportedVersion`) is 2; `PolicyDenied` and `PolicyUnavailable` are 1; every other facade error, and every error of the snapshot build, is 3. The mapping is `dctx_cli::exit::from_facade`. - `map hubs`, `map path` and `map export` report their facade errors as text: an `unknown id` end of `map path` is 1, anything else 3. - `dctx context` with no TARGET is 2; `dctx context --help` prints usage and exits 0. A TARGET that names nothing prints its empty page, then exits 1. - `dctx cache` exits 2 for a bad flag or value, a purge without `--root PATH`/`--all` or `--yes`, and a `--max-bytes` that would loosen the cap; 1 for a `--root` id the ledger does not hold; 3 when the cache directory, policy or ledger cannot be read or written (the message names the directory). - `dctx template` exits 2 for a bad flag and for a template that does not compile, and 3 when the template, the `--dir` directory or the `--output` file cannot be read or written (the message names the path). `--output` never writes through a symbolic link and refuses a target that is not a regular file. - `dctx` with no command opens the interactive menu only when stdin and stdout are terminals; otherwise it prints the short usage as a hint and exits 2. - `dctx doctor` follows the contract; `dctx rpc` keeps exit 0 at end of input (see Engine RPC below). ## Outside the contract `dctx plugin …` and `dctx git …` return the plugin host's own codes. ## Engine RPC `dctx rpc` uses the same operation paths and numeric taxonomy over [versioned NDJSON](protocol/README.md). Each reply carries `engine_version` and echoes its request id. An error contains the CLI code, diagnostic, hint and any stdout emitted before failure (including gone pages). Protocol/framing refusals use code 2 and leave the session usable. Cache status replies carry the same codes and hints as `dctx cache status`. An error reply does not change the server's process exit status: normal EOF exits 0, transport I/O errors exit 3, and broken stdout exits quietly with 0. The server performs no piggyback auto-clean. `pack --for TEXT --json` now emits the facade's context JSON page; its text member contains the same budgeted context page as plain `pack --for TEXT`. # Crate map Static checkout guide for contributors and coding assistants. 40 non-fixture Cargo packages: 36 under `crates/`, one plugin, one desktop, and two standalone tools. Root `Cargo.toml` includes crates, plugins and desktop; each tool declares its own workspace. `bindings/README.md` describes planned bindings; root membership for Python/Node is commented out. Fixture manifests under tests are not product crates. ## How to read the inventory Each row gives purpose, layer, direct first-party path dependencies, and direct external **normal** dependencies. `none` means std-only at that crate boundary; `first-party only` means no direct external normal dependency, not an assertion about the complete dependency closure. Dev/build dependencies are excluded. Optional and target-specific normal dependencies are explicitly marked. Resolved transitive dependencies and runtime behavior are **unverified** here. Source convention: for every row named `X`, purpose is taken from `crates/X/src/lib.rs:1` (first six lines), and dependency names from `crates/X/Cargo.toml` `[dependencies]`. These two paths are the row's evidence. Exceptions use the directory shown in the row. Desktop purpose comes from `apps/dctx-desktop/README.md:3`; its lib header has no purpose description. Layer labels are navigation classifications of those headers, using the accepted boundaries in `docs/design/ARCHITECTURE-DECISIONS.md` (DX-ARCH-01). ## Shipped CLI path (v1) What the `dctx` binary (`crates/dctx-cli`) actually runs, as of v1. No refactor: the other crates stay in the workspace. - **Shipped:** `dctx-cli` and the `crates/dctx` facade session (index, find, grep, callers, callees, neighbors, skeleton, hubs, pack, read), with dctx-core (selection), dctx-hash, dctx-ports, dctx-pack, dctx-template, dctx-adapter-cache, dctx-adapter-fs (compatibility IO), dctx-map-model (records and rendering) and the `dctx-lex-*` extractors. - **Request types only:** `dctx-map-query`. The CLI imports `Request`, `Verb`, `Direction`, `Format`, `AnswerBudget` and `EdgeKind`; its `Index` engine is never called. - **Internal or legacy (compiled as dependencies of `dctx-map-query`, not run by the CLI):** the `dctx-map-query` `Index` engine, `dctx-map-store`, `dctx-map-scan`, `dctx-map-resolve`, `dctx-map-segment`, `dctx-adapter-store`; `dctx-map-parse` likewise. docs/SPEC-MAP-MODE.md sections 6–8 and 10 describe this engine. - **Unstable (no stability promise in v1):** dctx-plugin-host, dctx-plugin-platform, dctx-plugin-protocol, dctx-plugin-distribution and dctx-desktop-api. The default `dctx-cli` build enables the plugin runtime and the bundled Git plugin process; `--no-default-features --features strict` builds without them. ## Core, engines and adapters | Crate | Purpose from header | Layer | Direct path dependencies | Direct external normal dependencies | | --- | --- | --- | --- | --- | | dctx-hash | First-party SHA-256 content digests. | pure core | none | none (std-only) | | dctx-core | Pure domain: ids, selection decisions, budgets, errors, pack facts and settings parsing. | pure core | dctx-hash | first-party only | | dctx-ports | Boundary traits Source, FactStore, Cache, Clock, Cancellation; in-memory implementations and spies. | pure core | dctx-core | first-party only | | dctx-map-model | IO-free map identities, byte spans, precision, provenance and answers. | pure core | dctx-hash | serde, serde_json (optional `wire-json`, enabled by default) | | dctx-map-segment | Pure safe codec for immutable map index segments. | pure core | dctx-hash | thiserror | | dctx-template | Pure DTS v1 renderer and v2 ContextPlan compiler. | mode engine | dctx-core, dctx-hash | first-party only | | dctx-pack | Pack snapshot and diff engine over injected ports, with no concrete IO. | mode engine | dctx-core, dctx-hash, dctx-ports | first-party only | | dctx-map-scan | Model-independent scan privacy rules. | mode engine | none | sha2, thiserror | | dctx-map-parse | Per-file syntax facts; PureParser over lexers, optional tree-sitter oracle. | lexer/parser | dctx-map-model, dctx-lex-rust, dctx-lex-js, dctx-lex-md, dctx-lex-py, dctx-lex-go, dctx-lex-java, dctx-lex-c, dctx-lex-cfg, dctx-lex-cs, dctx-lex-kt, dctx-lex-rb, dctx-lex-php, dctx-lex-swift | sha2, thiserror; optional: tree-sitter, tree-sitter-rust, tree-sitter-md, tree-sitter-javascript, tree-sitter-typescript (`syntax-tree-sitter`) | | dctx-map-resolve | Pure symbol resolution and move detection. | mode engine | dctx-map-model | thiserror | | dctx-map-store | Persistent graph facts, pack snapshots and content-addressed comparison cache. | adapter | dctx-core, dctx-hash, dctx-map-model, dctx-ports | rusqlite (`bundled`), thiserror, serde_json | | dctx-map-query | Incremental indexing and bounded traversal; wires scan, parse, resolve and store APIs. | mode engine | dctx-map-model, dctx-map-scan, dctx-map-parse, dctx-map-resolve, dctx-map-store, dctx-map-segment, dctx-ports, dctx-adapter-fs, dctx-adapter-store, dctx-adapter-cache, dctx-core, dctx-hash | thiserror, serde, serde_json | | dctx-adapter-fs | Confined filesystem Source adapter; selection before content. | adapter | dctx-hash | thiserror | | dctx-adapter-store | Filesystem publication of immutable map segments and manifest generations. | adapter | dctx-hash, dctx-map-segment | thiserror | | dctx-adapter-cache | Cache quotas, leases, expiry, persisted ledger and bounded auto-clean. | adapter | dctx-core, dctx-hash, dctx-ports | thiserror | ## Lexers and structural extractors Purpose below retains the language and extractor role from each lib header. Several headers say “zero-dependency”; manifests qualify that statement: the model-dependent lexers have first-party direct dependencies, and `dctx-map-model` defaults to external JSON dependencies. Do not infer an external-free closure from the header wording. | Crate | Purpose from header | Layer | Direct path dependencies | Direct external normal dependencies | | --- | --- | --- | --- | --- | | dctx-lex-rust | Structural Rust extractor built on syn. | lexer/parser | none | proc-macro2, quote, syn, thiserror | | dctx-lex-js | Hand-written JavaScript and TypeScript structural extractor. | lexer/parser | dctx-hash, dctx-map-model | first-party only | | dctx-lex-md | Hand-written Markdown structure extractor. | lexer/parser | none | none (std-only) | | dctx-lex-py | Hand-written Python structural extractor. | lexer/parser | dctx-hash, dctx-map-model | first-party only | | dctx-lex-go | Hand-written Go structural extractor. | lexer/parser | dctx-hash, dctx-map-model | first-party only | | dctx-lex-java | Hand-written Java structural extractor. | lexer/parser | dctx-hash, dctx-map-model | first-party only | | dctx-lex-c | Hand-written C and C++ structural extractor. | lexer/parser | dctx-hash, dctx-map-model | first-party only | | dctx-lex-cfg | Hand-written configuration structural extractor (JSON, TOML, YAML). | lexer/parser | dctx-hash, dctx-map-model | first-party only | | dctx-lex-cs | Hand-written C# structural extractor. | lexer/parser | dctx-hash, dctx-map-model | first-party only | | dctx-lex-kt | Hand-written Kotlin structural extractor. | lexer/parser | dctx-hash, dctx-map-model | first-party only | | dctx-lex-rb | Hand-written Ruby structural extractor. | lexer/parser | dctx-hash, dctx-map-model | first-party only | | dctx-lex-php | Hand-written PHP structural extractor. | lexer/parser | dctx-hash, dctx-map-model | first-party only | | dctx-lex-swift | Hand-written Swift structural extractor. | lexer/parser | dctx-hash, dctx-map-model | first-party only | ## Plugin infrastructure, facade and surfaces | Crate | Purpose from header | Layer | Direct path dependencies | Direct external normal dependencies | | --- | --- | --- | --- | --- | | dctx-ed25519 | Ed25519 verification for plugin trust, via audited ed25519-dalek. | pure core | none | ed25519-dalek | | dctx-plugin-protocol | Std-only codec and typed records for frozen plugin API v1. | plugin | none | none (std-only) | | dctx-plugin-host | Plugin host domain and brokers; authority, receipts, resources, lifecycle and hooks. | plugin | dctx-hash, dctx-plugin-protocol | first-party only | | dctx-plugin-platform | Native plugin admission and platform security primitives; general native launches fail closed. | adapter | dctx-hash, dctx-plugin-protocol | thiserror; Linux-only: rustix, landlock, seccompiler (target dependency section) | | dctx-plugin-distribution | Plugin installer, trust and discovery client: signed manifests, offline bundles, atomic activation. | plugin | dctx-ed25519, dctx-hash, dctx-plugin-protocol | first-party only | | dctx-plugin-git (`plugins/dctx-plugin-git/`) | Bundled git plugin: local .gitignore protection and brokered git add .gitignore. | plugin | dctx-plugin-protocol | first-party only | | dctx | Stable library facade for pack, map, templates, cache and optional plugin host. | facade | dctx-adapter-cache, dctx-core, dctx-hash, dctx-lex-js, dctx-lex-md, dctx-map-model, dctx-pack, dctx-ports, dctx-template; optional: dctx-lex-rust, dctx-plugin-host, dctx-plugin-platform, dctx-plugin-protocol | first-party only | | dctx-cli | Library surface for cache administration; dctx binary wires the same modules. | surface | dctx, dctx-adapter-cache, dctx-core, dctx-map-query, dctx-plugin-distribution, dctx-plugin-protocol, dctx-template; optional: dctx-plugin-git | first-party only | | dctx-desktop-api | Desktop engine seam for snapshots, settings, recent projects and plugin management. | surface | dctx, dctx-plugin-distribution, dctx-template | serde, serde_json | | dctx-desktop (`apps/dctx-desktop/src-tauri/`) | Cross-platform GUI for dctx — Directory Context Generator (app README). | surface | dctx-desktop-api, dctx-plugin-distribution, dctx-plugin-protocol | tauri, tauri-plugin-shell, tauri-plugin-dialog, tauri-plugin-clipboard-manager, serde, serde_json, tokio, chrono, dirs | | architecture-bench (`tools/architecture-bench/`) | Baseline for current dctx map mode. | tool | dctx-map-query | serde, serde_json, sha2, thiserror | | plugin-index (`tools/plugin-index/`) | Local public-index validator for plugins. | tool | dctx-ed25519, dctx-hash | thiserror | Tool purpose evidence: each tool's `src/lib.rs:1`; dependencies: its Cargo.toml. Plugin purpose evidence: `plugins/dctx-plugin-git/src/lib.rs:1`. Desktop dependencies: `apps/dctx-desktop/src-tauri/Cargo.toml`. `tauri-build` is a desktop **build** dependency, outside the normal-dependency columns. Linux plugin dependencies are the one target-specific addition above. The facade does not directly depend on dctx-map-query: do not turn an intended architectural boundary into an invented Cargo edge. Its optional Rust extractor uses `syntax-rust`; plugin runtime dependencies use `plugin-runtime`. ## Dependency picture: core toward consumers This is a selected-edge tree, not an exhaustive DAG. Children consume parents; repeated nodes have other inputs listed in the inventory. Every edge shown is a direct path dependency in the child's manifest. Braces group sibling crates. ```text dctx-hash |-- dctx-core | |-- dctx-ports | | `-- dctx-pack | | `-- dctx | | |-- dctx-cli | | `-- dctx-desktop-api | | `-- dctx-desktop | `-- dctx-template --> {dctx, dctx-cli, dctx-desktop-api} |-- dctx-map-model | |-- dctx-lex-{js,py,go,java,c,cfg,cs,kt,rb,php,swift} | | `-- dctx-map-parse <-- {dctx-lex-rust, dctx-lex-md} | | `-- dctx-map-query | | |-- dctx-cli | | `-- architecture-bench | |-- dctx-map-resolve --> dctx-map-query | `-- dctx-map-store --> dctx-map-query |-- dctx-map-segment | `-- dctx-adapter-store --> dctx-map-query |-- dctx-adapter-fs --> dctx-map-query |-- dctx-adapter-cache --> {dctx, dctx-cli, dctx-map-query} |-- dctx-plugin-host --> dctx [optional] |-- dctx-plugin-platform --> dctx [optional] |-- dctx-plugin-distribution --> {dctx-cli, dctx-desktop-api, dctx-desktop} `-- plugin-index dctx-map-scan --> dctx-map-query dctx-ed25519 --> {dctx-plugin-distribution, plugin-index} dctx-plugin-protocol `-- {dctx-plugin-host, dctx-plugin-platform, dctx-plugin-distribution, dctx-plugin-git, dctx [optional], dctx-cli, dctx-desktop} dctx-plugin-git --> dctx-cli [optional] ``` ## Language wiring Authoritative variants and extension selection: `crates/dctx-map-parse/src/domain/facts.rs:8` (`Language`, `for_path`). Dispatch: `crates/dctx-map-parse/src/adapters/mod.rs:40` (`PureParser`). Adapter paths below are relative to `crates/dctx-map-parse/src/adapters/`; each file imports the named lexer. These are all 13 `dctx-lex-*` packages. | Language variant(s) | Lexer crate | Adapter | | --- | --- | --- | | Rust | dctx-lex-rust | rust.rs | | JavaScript, TypeScript, Tsx | dctx-lex-js | javascript.rs | | Markdown | dctx-lex-md | markdown.rs | | Python | dctx-lex-py | python.rs | | Go | dctx-lex-go | go.rs | | Java | dctx-lex-java | java.rs | | C (C and C++) | dctx-lex-c | c.rs | | Config (JSON/JSONC, TOML, YAML) | dctx-lex-cfg | config.rs | | CSharp | dctx-lex-cs | csharp.rs | | Kotlin | dctx-lex-kt | kotlin.rs | | Ruby | dctx-lex-rb | ruby.rs | | Php | dctx-lex-php | php.rs | | Swift | dctx-lex-swift | swift.rs | | Unknown | none | mod.rs fallback: module-only | The optional `TreeSitterParser` in `adapters/mod.rs:74` uses grammars for Rust, JavaScript/TypeScript/Tsx and Markdown. Other known languages take the pure adapters; Unknown takes fallback. This is an oracle feature, not the default. ## Cross-cutting rules and evidence locations - **No Git in the core:** [product contracts](design/PRODUCT-CONTRACTS.md) records the core ban and plain-text .gitignore exception. Enforcement evidence: `crates/dctx-map-query/tests/no_git.rs` (source spawn audit, PATH trap and source-port privacy tests). VCS effects belong to the plugin, not the core. - **Privacy, selection before content:** `crates/dctx-adapter-fs/tests/privacy.rs` uses read spies to check ignored/omitted paths remain unopened; `crates/dctx-map-query/tests/source_privacy.rs` checks secrets, ignored files, traversal and symlinks, with an included-file positive control. - **Pure domain boundary:** `crates/dctx-core/src/lib.rs:1` points to `crates/dctx-core/tests/purity.rs`, which checks every source module without a directory exemption. Comments and unit-test tails are excluded from the IO scan. The crate retains its first-party dctx-hash dependency. - **Plugin PP1–PP10:** [historical PP matrix](archive/design/plugin-evidence/PP-MATRIX.md) maps tests, formal evidence and gaps: PP1 authority narrows; PP2 excluded-source privacy; PP3 effect audit; PP4 protocol binding; PP5 no blind replay; PP6 strict isolation; PP7 bounded resources; PP8 lifecycle progress; PP9 install integrity; PP10 hook order/result truth. The matrix is dated scout evidence, not a fresh passing test result or certification of today's product acceptance. - **Legacy removal:** The migration removed the core IO wrappers and their exports. [legacy removal inventory](archive/design/D3-LEGACY-REMOVAL.md) remains the historical inventory; [compatibility record](archive/design/D3-COMPATIBILITY.md) maps retired families to retained tests. Pack codecs, template rendering, filesystem adapters and CLI compatibility IO own the replacements. Pure core modules, settings and template assets remain. ## Validation commands Use [TESTING.md](TESTING.md) for the current commands, toolchains, matrix and exclusions. Desktop backend checks use `tools/desktop-check.sh`; browser evidence uses `bun run e2e` from `apps/dctx-desktop`. A skipped desktop check does not qualify a desktop release. Standalone tools have their own workspaces and checks. # Choosing how to use dctx Compare dctx with **grep plus reading files**, and choose by the work you need to do. Smaller tool output is useful, but total agent cost also includes startup instructions, tool definitions, conversation history and the number of model turns. A tool call can require another model request carrying that context again; provider caching can change its billed cost. Count both calls and session tokens. ## Available surfaces and publication status | Modality | Install | Status | Best for | |---|---|---|---| | CLI / interactive terminal | [Prebuilt archives](https://github.com/Eris-Margeta/dctx/releases/tag/v1.3.1), or [build from source](../README.md#from-source) | Available now; crates.io publication pending | One-off chat (`pack --clipboard`), shell agents, scripts and CI; run `dctx` for the terminal menu | | Rust library (`dctx` facade) | Tagged Git dependency in the [library section](#rust-library-embed-the-facade) | Available from Git; crates.io publication pending | Embedding pack, map, templates and cache in Rust tools and editors | | Desktop app | [Build the Tauri app](../apps/dctx-desktop/README.md#quick-start) | Tauri 0.11 preview today; GPUI rebuild planned | Selecting projects and generating snapshots in a GUI | | Python, Node and Go wrappers | `npm install @tejl/dctx` for Node; CI artifacts for Python and Go; see [language wrappers](#python-node-and-go-wrappers) | Node published on npm; all wrappers tested in CI | Calling the engine over `dctx rpc` from Python, Node or Go projects | From version 1.3.1, the npm release publishes `@tejl/dctx` with pinned `@tejl/dctx-` optional dependencies. Python and Go wrappers are available as CI artifacts; the Rust facade is available as a tagged Git dependency. Native release archives remain available for system installation or an explicit `DCTX_BIN` path. ## Choose by task | Your situation | Start here | Avoid it when | |---|---|---| | Human, one-off chat | `dctx pack . --clipboard` | The selected tree is too large to paste or contains irrelevant material | | Short agent task | Grep, then read the matching file or lines | Add dctx only if a focused query saves enough work to cover setup and extra turns | | Long agent session / big files | `find` -> `read --json`, with `skeleton` for orientation | The needed file is already small or a grep plus narrow read gives the same answer | | Huge tree, monorepo, data or Markdown corpus | Run from a relevant subfolder; apply ignore rules before scanning | You need an unscoped index of 100 GB+ or expect a budget flag to reduce the scan | | CI / repeated prompt prefix | Deterministic `pack` or scoped map output saved as an artifact | You expect dctx alone to guarantee provider cache hits | ## Human, one-off: pack to clipboard From the project or relevant subfolder: ```sh dctx pack . --clipboard ``` Paste the resulting structured context into your chat. The local clipboard must be available. To inspect or save the same selection instead: ```sh dctx pack . --output context.txt ``` Do not use an unbounded whole-project pack for a large tree or when only one function matters. Narrow the root first, or use map reads. Pack's `--ext rs,toml` and `--small 1` filters can restrict extensions and file sizes (MB); they are pack filters, not map index limits. Inspect the content before sharing it. ## Short agent task: grep can be enough If you know a name and expect only a few file reads, use the existing shell: ```sh grep -R -n -F --include='*.rs' 'struct Session' crates/dctx/src sed -n '130,170p' crates/dctx/src/session/mod.rs ``` Choose the line range from the search result; reading a narrow range is an honest baseline alongside whole-file reads. If a symbol read is useful, call `dctx map find Session` through the existing shell. Verbose agent instructions add starting context; measure their cost before adding them for a tiny edit. ```sh cd crates/dctx-lex-go dctx map find Add --budget 500 --limit 5 dctx map read 's:tests/fixtures/basic.go#Add' --json dctx map skeleton tests/fixtures/basic.go --budget 1000 ``` For your project, use the exact ID returned by `find`. Both text `read` and `read --json` include verified source bytes; JSON carries them in `source_utf8`. Skeletons show declaration signatures without bodies. If an answer has `more` and `next`, pass that opaque `next` value with `--cursor` on the same request, and count the extra call. Budgets are estimated output tokens, not a model tokenizer promise. ## Huge trees: scope before indexing A 100 GB+ folder, including a 200 GB working tree, is a container of possible scopes, not a promise that dctx can index it all at once. Source volume, visited entries, record count and cache size are separate limits. Markdown headings produce document nodes, so mostly text trees can still have large indexes. Map's shared cache stores a lifecycle ledger (`ledger.v1`), policy (`policy.v1`), serialized generations and their view manifests in managed object files. A map generation contains file inventory, digests and stat stamps, declarations, summaries, signatures, source spans and edges. It is not a copy of the whole source tree or an embedding store; exact source reads still verify live files. A compatible unchanged generation can be reused across CLI processes. The product hard cap is **2 GiB (2,147,483,648 accounted bytes)** across the shared cache. Defaults also include a 1.5 GiB soft watermark and a roughly 1.2 GiB cleanup target. Admission evicts reclaimable generations first, preserving live reader leases. If the new generation still cannot fit, the query fails with a cache-limit error; it does not quietly return a complete partial index. Repeating the same unscoped request will not fix this. The cap is not a RAM-usage or exact filesystem-size guarantee. `cache config --max-bytes` can only tighten it. Start at the relevant package, not the huge parent: ```sh cd packages/service-a dctx map find Config --budget 500 --limit 5 # Equivalent root selection from elsewhere: dctx map find Config --place packages/service-a --budget 500 --limit 5 ``` `--place` selects the scan root. `--in src` narrows find/grep matches **after** indexing; `--budget`, `--limit` and `--cursor` bound answers, not the tree scan. Running from a subfolder changes relative paths and IDs; retain the needed ignore rules there instead of assuming parent project rules were inherited. Use existing `.gitignore` and a `.dctxignore` at the chosen root to exclude data, generated output and irrelevant documents before reads, parsing and caching. For example, merge these project-specific entries into `.dctxignore`: ```gitignore /data/ /generated/ /archive/ ``` The host loads the global ignore file, root and nested `.gitignore` rules, then the root `.dctxignore`. Built-in sensitive-file and `.git` exclusions still apply. The global ignore file is `/dctx/ignore`: `$XDG_CONFIG_HOME/dctx/ignore` or `~/.config/dctx/ignore` on Linux and macOS, `%APPDATA%\dctx\ignore` on Windows. dctx does not read Git metadata, so `.git/info/exclude` and Git's `core.excludesFile` are not applied; put those patterns in `.dctxignore` or the global ignore file. Do not set `DCTX_INDEX_IGNORED=1` when relying on these ignore rules. The built binary documents these **environment variables**, not scan-limit flags: | Variable | Default | Accepted range / effect | |---|---|---| | `DCTX_MAX_SOURCE_BYTES` | 1,073,741,824 (1 GiB) | 1–17,179,869,184 total source bytes per scan | | `DCTX_MAX_RECORDS` | 1,000,000 | 1–100,000,000 files, symbols and edges | | `DCTX_MAX_ENTRIES` | 100,000 | 1–100,000,000 visited files and directories | For a deliberately smaller scope and fail-fast ceilings: ```sh DCTX_MAX_SOURCE_BYTES=268435456 DCTX_MAX_RECORDS=250000 DCTX_MAX_ENTRIES=25000 \ dctx map find Config --place packages/service-a --budget 500 --limit 5 dctx cache status --json dctx cache gc --dry-run ``` Limits refuse an oversized scan; they do not produce an exhaustive answer from a truncated scan. Raising source or record ceilings does not raise the 2 GiB cache cap. A different absolute `DCTX_CACHE_DIR` selects a separate cache location, not a larger cap. Do not use dctx on the whole huge tree if narrowing would exclude facts your task requires; use grep and direct reads across the needed directories, or query several explicit scopes and account for extra calls. ## CI / prompt-cache prefix stability Save deterministic output from a fixed selection as a build artifact: ```sh dctx pack . --output context.txt dctx map find Session --json > symbol-context.json ``` Keep generated artifacts outside the next scan or ignore them. Keep the default `--tree-stamps=off` for stable prefixes. For map, leave `--meta` off to exclude changing snapshot, generation and age metadata. Keep stable instructions and context early in the assembled prompt, followed by changing task text. Use the same template, root, request and binary version. The [stability report](research/stability-20261105/REPORT.md) measured 33/33 text and 33/33 JSON answers unchanged after unrelated edits on three Linux corpora, and identical output over five runs. It measured answer bytes, not provider cache hits, billed tokens or whole-session latency. A bare `touch` leaves default pack output unchanged; a real edit can preserve the bytes before the edited file. Do not assume every edit preserves the entire prompt, or that provider cache retention and minimum-prefix requirements are controlled by dctx. ## Rust library: embed the facade The supported entry point for Rust integrations is the [`dctx` facade](../crates/dctx), which exposes `Session`, `SnapshotRequest`, `MapRequest`, `PackRequest`, sinks, templates and cache operations. Internal engine crates are implementation details. The facade is available from Git now; **crates.io publication is pending**. In your application's `Cargo.toml`: ```toml [dependencies] dctx = { git = "https://github.com/Eris-Margeta/dctx", tag = "v1.3.1" } ``` The [ten-line pack example](../README.md#use-as-a-library) is compiled and run as a [workspace doctest](../examples/library/README.md). It uses an in-memory source and an explicit 8 MiB ephemeral storage ceiling, so it needs no CLI subprocess or project scan. Run it from this repository's root: ```sh cargo test --locked -p dctx-library-example --doc ``` The host supplies source, clock, cancellation, selection policy, grants, storage and place/view names. The facade does not discover a home directory, global configuration, Git executable or plugin host; it does not print to stdout. The example's `println!` belongs to the caller. A `VecSink` collects the encoded pack or query answer for your application to consume. For filesystem use, open an `FsSource` at a scoped root and supply a live `Clock`. The source does **not** automatically load `.gitignore`; the host must pass its ignore-rule texts through `RuleTexts` / `SelectionPolicy`. Choose storage ceilings and persistence explicitly. The CLI supplies its own config, rules and cache lifecycle, so copying a library call without that host policy is not equivalent to invoking the CLI. ## Desktop app: Tauri preview today The [desktop app](../apps/dctx-desktop/README.md) is a Tauri 2 app, currently the 0.11 preview. It uses `dctx-desktop-api` and the shared Rust facade. Build it from source using the app's [quick start](../apps/dctx-desktop/README.md#quick-start); the CLI archives do not install a desktop application. A GPUI rebuild is planned, not the current downloadable or buildable desktop implementation. ## Python, Node and Go wrappers Thin wrappers over the versioned [`dctx rpc` protocol](protocol/README.md) live in [packages/python](../packages/python/README.md), [packaging/npm/dctx](../packaging/npm/dctx/README.md) (which also forwards the `dctx` CLI command) and [packages/go](../packages/go/README.md). Each starts the native engine, passes CLI argument strings and returns the engine's bytes unchanged; CI checks byte parity with the CLI. Install the Node wrapper with `npm install @tejl/dctx`; npm includes the matching pinned `@tejl/dctx-` optional dependency. Install Python and Go wrappers from CI artifacts or a checkout, as each README describes, and point them at an engine from the [GitHub release archives](https://github.com/Eris-Margeta/dctx/releases) that has `dctx rpc`. Their arguments carry full CLI authority, so never pass untrusted values as `--place`, `--output` or dash-leading arguments. Without a wrapper, any language can invoke the CLI as a subprocess and consume `--json` map answers. Use the Rust facade when you need an in-process engine. # The dctx Context Management Specification Version 1.0 · draft 2 · 21.10.2026 · Apache-2.0 · measured against `docs/research/trail-code-2026-10` (dctx `17dff0b`, Trail-Code 0.23.1) This document specifies **dctx**, a context engine for AI-assisted software development. It is normative where it uses **MUST**, **MUST NOT**, **SHOULD** and **MAY** (RFC 2119). Every claim it makes about the product is either marked **landed** (present in the repository today), **contract** (a versioned contract in `docs/design/contracts/` that is partly implemented) or **target** (specified here, not yet built), and every target carries an acceptance gate. Nothing in this document is a marketing number: measured values cite the pinned benchmark in `docs/research/trail-code-2026-10/REPORT.md` or the contract that defines them. --- ## Contents - **Part I — Principles** 1. Purpose and the workflows served 2. The core belief: prompt-processing efficiency 3. Zero RAG defects 4. Privacy and authority - **Part II — Model** 5. Identity 6. The graph: nodes, ids, outcomes 7. Edges, confidence and provenance 8. Precision labels 9. Freshness - **Part III — Answers** 10. The verbs 11. Page formats and byte stability 12. Tiers, deltas, deduplication and compression levels 13. Token estimation - **Part IV — Policy** 14. One language: DTS v2 15. The seven-layer policy lattice 16. Organization bundles, signing and enrollment 17. Explain and receipts - **Part V — Index** 18. Segments, manifests and the per-file fact store 19. Freshness check and incremental rebuild 20. Cold build 21. Ranking - **Part VI — Extension** 22. Core, surface or plugin: the decision procedure 23. Plugin protocol and its v1.x extensions 24. Surfaces: CLI, library, agent hooks, bindings, desktop 25. Blast radius 26. Learnings - **Part VII — Assurance** 27. Dependencies and build profiles 28. Conformance suite 29. Formal models 30. Versioning and compatibility - **Part VIII — Delivery** 31. Roadmap and acceptance gates (31.0 Measured baseline · 31.1 Phases) 32. Non-goals - Appendices: A. Lineage · B. Comparison with Trail-Code · C. Reserved names · D. Document map --- # Part I — Principles ## 1. Purpose and the workflows served dctx turns a directory of source code into **the smallest, most cache-stable, provably authorized set of bytes that lets a model or a human act correctly** — and it can prove each of those four adjectives with a test. It is one engine for every way software is built today: | Workflow | dctx instrument | What "efficient" means there | |---|---|---| | Hand-coding, reading a new codebase | `dctx map` outline, `find`, `read`; desktop app (free) | Fast orientation without opening forty files | | Copy-paste into a chat assistant | `dctx pack` (full / diff), templates, clipboard | Fewest bytes that still let a human and a model share one view; re-send only what changed | | Tab completion and IDE assistants | library facade (`crates/dctx`), bindings | Freshness in ≤50 ms, span reads in milliseconds, for the editor's own context budget | | Agents with a shell tool | `dctx map ` | One line per record, copyable ids, bounded pages, always a next step | | Software factories and CI | facade + organization policy + plugins | Deterministic bytes under one signed policy; receipts; no network unless granted | dctx is not a code search engine, not a vector store, not an IDE and not a model. It never calls a model and never sends a byte off the machine on its own. The measured baseline for every claim below is §31.0. ## 2. The core belief: prompt-processing efficiency Every token placed in a model's context is paid for three times: | Cost | What it is | What dctx controls | |---|---|---| | **Prefill** | Input tokens the model must process before it answers. Billed per token; latency grows with it | Bytes per answer; spans instead of whole files; structural compression | | **Cache misses** | Providers serve repeated prompt prefixes from a cache at a fraction of the price and latency. One changed byte early in a prompt invalidates everything after it | Byte-stable rendering, canonical order, stable ids, prefix-stable tiers | | **Attention dilution** | Answer quality falls as irrelevant tokens grow | Ranked, bounded answers; one span per read; no repeats within a session | dctx on its own does not save tokens by default. Savings belong to a harness or agent system that reuses byte-identical, prefix-stable context across long sessions over a large body of work, with control over every byte. No measured, citable savings figure for such a system exists yet; see the [philosophy](WHY-DCTX.md#savings-belong-to-the-system) and [whole-session benchmark](BENCHMARK-20261111.md). dctx treats these as engineering constraints, not goals. A conforming implementation MUST satisfy the five **PPE** constraints: | Id | Constraint | Status | |---|---|---| | **PPE-1 Bounded** | Every answer has a declared byte and estimated-token ceiling, reserved before records are written; records are never split | landed (`dctx_core::budget`, API-PORTS-v1 `BoundedSink`) | | **PPE-2 Deterministic** | Same source snapshot, policy, plan, ranking revision and request => identical bytes, on every OS and thread count | landed on Linux (every text verb identical over 5 runs; property P6, canonical payload); cross-OS gate open (§11) | | **PPE-3 Prefix-stable** | Context injected across turns is layered so that bytes that did not need to change do not change (§12) | tier layering remains target (§12.1); on 2026-11-06, `0495f5f` preserved 33/33 text and 33/33 JSON answers after unrelated comment edits on three pinned local corpora; all identical over five runs, paired-answer M7 = 1.0 ([protocol and limits](research/stability-20261105/REPORT.md)); historical baseline 0/63 (§31.0) | | **PPE-4 Non-redundant** | Within one session a record already delivered is not re-sent unless its content changed (§12.4) | target | | **PPE-5 Honest** | Every answer states its freshness, precision and provenance; the engine never asserts what it does not know | landed (`precision.*`, `freshness.*` in the wire format) | Seven metrics measure them. M1–M5 come from the map-mode design; M6–M7 make prompt caching first-class: | Metric | Definition | |---|---| | M1 | Input tokens per accepted task | | M2 | Exploration tokens per task (results of read-only tool calls, including dctx's own output) | | M3 | Tool calls before the first edit | | M4 | Task acceptance rate — the guard: no saving counts if M4 falls | | M5 | dctx's own output tokens (counted inside M2, so the tool cannot hide its cost) | | M6 | Provider prefix-cache hit ratio: cached input tokens ÷ input tokens | | M7 | Prefix stability: common byte prefix of consecutive injected context blocks ÷ block length. Measured today as answers identical after an unrelated edit: 0/63 (comparison tool 59/70) | | M8 | Task recall: gold facts found ÷ gold facts on the published 70-question set — the offline proxy for M4. Baseline 169/354 = 0.48; comparison tool 312/354 = 0.88 | **Rule.** A feature without an acceptance gate stated in M1–M8, or in a latency, memory or correctness bound measured by the suites in §28, is not a dctx feature. M8 (offline) or M4 (online) MUST accompany any token-saving claim: a tool that answers nothing is infinitely efficient. ## 3. Zero RAG defects Retrieval-augmented generation over embedded chunks fails in characteristic ways. dctx names ten defect classes, eliminates each by a specific mechanism, and ships a **defect corpus** — fixtures with a positive control per class — that `dctx conformance` runs (§28). A build that fails any row MUST NOT call itself dctx-conformant. | # | Defect class | Symptom | dctx mechanism | Status | |---|---|---|---|---| | R1 | Fragmentation | Chunks cut through declarations; signature without body | Records are syntax-owned spans; `read` returns the whole node or a marked prefix with a continuation; records are never split | landed | | R2 | Non-determinism | Same question, different chunks (approximate search, insertion-order ties) | Integer scores, order (score desc, id asc), frozen ranking revision, canonical payload | landed | | R3 | Staleness | Index built from old bytes, served as current | There is no incremental index and no stale flag. Every CLI process re-walks the tree and re-hashes the selected files; a persisted generation is reused only when every content digest still matches, and any change rebuilds the whole generation. Inside one session `read` re-hashes the bytes against the snapshot digest and refuses with `SourceChanged` when they differ. The CLI always takes strict snapshots, so `freshness.state` is always `"verified"` (the library reports `"metadata"` only for a `FreshnessMode::Metadata` request) | landed (re-verify on every process; no stale flag) | | R4 | Positional identity | Chunk ids that shift when a file is added | Path + qualified-name ids with ordinals; explicit `moved`, `gone`, `ambiguous` outcomes | landed | | R5 | Semantic drift | "Similar" but wrong code | Lexical ranking over split identifiers, exact-name boost, kind filters, then graph edges with explicit confidence | contract — lexical ranking landed; graph edges are **not emitted by the shipped CLI** (TC-F01); the resolver is landed in `crates/dctx-map-resolve` but not wired (§7); `typed` rung target | | R6 | Authority leak | Secrets, ignored and generated files reach the prompt | Selection precedes content: excluded files are never opened; policy rechecked at emission; plugins never receive excluded bytes | landed for map and pack: the strict secret-shaped deny of §4 item 3 has no override | | R7 | Unbounded context | Top-k chunks of unknown size crowd out instructions | Hard per-verb caps; byte ceiling derived from tokens; envelope reserved first | landed for map verbs; the legacy tree (`dctx . -t`) and `pack` are unbounded (974 KB and 8.7 MB measured) and are not conformant surfaces | | R8 | Opaque provenance | The model cannot tell a fact from an inference | Every record carries parser and coverage; every edge carries confidence and source | landed for records; vacuous for edges until §7 lands | | R9 | Hidden tool cost | The retrieval tool's own output is not counted | M5 inside M2; `dctx bench tokens` (§28) | target | | R10 | Summary drift | Model-written summaries describe code as it was | The engine never calls a model; imported summaries are served only while their body fingerprint matches | landed (rule); import target | Embeddings never enter the core. If lexical recall is ever proven insufficient on the public corpus, ranked candidates MAY arrive as a plugin overlay with provenance `embedding:` — labeled, optional, never default. ## 4. Privacy and authority 1. **Selection before content.** A path is classified (`Include`, `Exclude`, `OmitContent`, `DebugVisible`) before any byte of it is read, hashed, parsed or cached. `Exclude`, `OmitContent` and `DebugVisible` never authorize content. Landed; evidence: read-spy tests in `crates/dctx-adapter-fs/tests/privacy.rs` and `crates/dctx-map-query/tests/source_privacy.rs`. 2. **Rules.** Built-in defaults, repository `.gitignore` files (read as plain text), `.dctxignore` and policy (`privacy.ignore`) combine. Landed for pack and map. 3. **Secret-shaped files (landed for v1).** A strict, built-in deny covers `.env`, `.env.*`, `*.env`, `.envrc`, `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.jks`, `*.keystore`, `id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519` (and `_`/`-` suffixed variants), `.netrc`, `_netrc`, `.npmrc`, `.pypirc`, `.pgpass`, `.htpasswd`, `.git-credentials`, `credentials`, `credentials.`, `*.credentials.json` and `secrets.` (data = json, yaml, yml, toml, ini, xml); ADR-014 "SENSITIVE" is the normative list. Such files appear in trees with content omitted and are never read, hashed or indexed by pack or any map verb. v1 has no override: no `--allow-sensitive` flag, and no local rule can negate the deny. Policy MAY later add named classes (`aws`, `gcp`, `ssh`, `jwt`). dctx never scans contents to decide. **Gate:** the adversarial corpus's planted `.env` value is absent from `pack` output and from the map cache; the path is listed. Checked for every shape and every command by `/scripts/checks/V1-1.zsh` (TC-F08 is closed). 4. **No VCS in the core.** The core never reads `.git/`, never spawns `git`, never uses VCS object ids. Identity is dctx's own digest (§5). VCS-aware behaviour is a plugin. Landed (`crates/dctx-map-query/tests/no_git.rs`). 5. **No network in the core.** No telemetry, no update checks, no model calls. The only legal telemetry value in policy is `"none"`. Measured: zero socket system calls in every audited dctx run (§31.0). 6. **Re-check at emission.** Policy is checked again before bytes leave the engine, even for a pinned snapshot. A policy change invalidates cached authorization. --- # Part II — Model ## 5. Identity Identity is defined by `docs/design/contracts/IDENTITY-v1.md` and summarized here. | Key | Definition | |---|---| | `ObjectKey` | Algorithm-tagged first-party SHA-256 of the exact authorized bytes, plus byte length (`crates/dctx-hash`) | | `FactKey` | `ObjectKey` + language + parser identity and revision + extraction-rule digest | | `SourceSnapshot` | Sorted manifest of (path, stamp, `ObjectKey`) for the authorized view | | `ViewKey` | Snapshot digest + selection-policy digest + plan digest | | `view` digest (target) | SHA-256 over the `ViewKey` framing and the canonical request bytes; printed in the provenance trailer (`--provenance`, §11) so a caller can name what it already holds | | Policy digests | One per layer plus the effective digest (§15); part of `ViewKey` | Git hashes are never an input and never a fallback. ## 6. The graph: nodes, ids, outcomes Nodes: `place`, `package`, `module`, `symbol` (with kinds `fn`, `method`, `struct`, `enum`, `trait`, `impl`, `const`, `macro`, `class`, `interface`, `type`, `test`) and `doc` sections. Ids are stable, human-copyable strings: ```text m:crates/dctx/src/lib.rs module s:crates/dctx/src/lib.rs#Session symbol (qualified name; ~n ordinal on collisions) d:docs/SPEC.md#the-graph document section @3f9c1a alias for ids longer than 120 bytes ``` A request for an id that no longer resolves returns an **outcome**, never a silent empty answer: `moved` (with the new id, from body-fingerprint evidence), `gone`, or `ambiguous` (with candidates). ## 7. Edges, confidence and provenance Edge kinds: `contains`, `imports`, `calls`, `implements`, `uses-type`, `tests`, `documents`, `reexports`. **Status.** Kinds and the confidence lattice are landed in `dctx-map-model`; reference extraction is landed in the lexers; resolution is landed in `crates/dctx-map-resolve`. **The facade index (`crates/dctx/src/index`) emits only `contains` edges today**, so `neighbors --edge calls|imports` was empty on 140 of 140 benchmark targets (§31.0). Wiring the resolver into the index is P0 (§31). Confidence is a four-rung lattice. Every edge carries exactly one rung and a source: | Rung | Meaning | Source | |---|---|---| | `exact` | Bound by syntax and scope, or by an import that resolves to a file in the view, or supplied by a compiler-grade overlay. Measured expectation: a comparison tool reaches precision 0.94–1.00 at recall 0.10–0.96 with syntax-and-scope binding alone; dctx MUST reach precision ≥ 0.95 before its edges may be shown without a `guess` label | lexer + resolver; `lsp:@` overlays | | `typed` (target) | Method call resolved through the receiver's inferred type (§7.1) | binder | | `name` | Unique declaration with that name in scope or in the view | resolver | | `guess` | Bare-name match among several candidates | resolver | An edge labeled `exact` that is wrong is a **defect**, not a statistic. ### 7.1 The binder (target: `dctx-map-bind`, pure crate) A scope graph sits between parse and resolve. Lexers add three cheap per-reference fields: `receiver` (head identifier of the receiver expression), `arity`, and `binding_hint` (declared annotation, constructor name or import alias that produced a local). Resolution walks: 1. lexical scopes outward (shadowing honored) -> `exact` on a unique declaration; 2. imports, resolved to files from the view inventory and manifests already lexed by `dctx-lex-cfg` (`tsconfig` paths, `go.mod`, `Cargo.toml`, `composer.json`, `pyproject`, SwiftPM targets) -> `exact`; 3. the receiver's type by shallow, deterministic rules — `self`/`this`, constructor, annotation, field type, import alias, annotated return type of the last call in a chain — then the method among that type's members and its declared supertypes -> `typed`; 4. a unique declaration in the view with a compatible kind -> `name`; 5. otherwise `guess` or unresolved. No unification, no cross-assignment inference, no generics. Anything deeper is the job of the compiler-grade overlay plugin (§23.2), whose edges carry provenance and never replace first-party facts. **Gates.** Measured on the published gold (`docs/research/trail-code-2026-10/data/targets/`, 140 definition targets in five categories, micro-averaged over call sites): | Phase | Requirement | |---|---| | P0 (resolver wired) | precision ≥ 0.95; recall ≥ 0.88 on *rare* (comparison 0.93), ≥ 0.81 on *collision* (0.86), ≥ 0.35 on *hub* (0.42), ≥ 0.25 on *receiver* (0.56); zero wrong `exact` | | P3 (binder) | receiver recall ≥ 0.56, interface name-level recall ≥ 0.42, hub ≥ 0.42; `exact ∪ typed` precision ≥ 0.95; zero wrong `exact`; callees question ≥ 10/14 (today 2/14) | The same corpus is run against other tools for any published comparison. A held-out edge corpus of ≥50 labeled call sites per language (TypeScript, Python, Go, Java first) extends it before the `typed` rung is promoted. ## 8. Precision labels Every answer carries `precision.coverage` (`structural` | `syntax` | `opaque`), `precision.completion` (`complete` | `partial` | `refused`) and `precision.parser` (for example `dctx-structural/1`, `syn/2`). Unsupported files are `opaque`: listed, never invented. Landed. **Omissions (target, P1).** `precision.omitted` counts paths excluded for reasons other than policy — `{binary, unnamed, oversize, capped}` — so an agent knows the map is incomplete (TC-F13: non-UTF-8 names, names containing a newline and NUL-containing sources were skipped silently). Files whose facts exceed `extraction.max_facts_per_file` are labeled `partial` (TC-F07: one 6.7 MB JSON fixture produced 235,842 symbols and a 158 MB generation, 2.9 times the working tree). ## 9. Freshness | Mode | Meaning | |---|---| | `metadata_validated` | Stamps (size, mtime, inode where available) agree with the manifest; touched files are digest-verified | | `strict_live` | Every authorized file in scope is digest-verified before answering | | `pinned` | The answer is served from a named snapshot digest | `read` always verifies its own bytes, in every mode (landed). Answers carry `freshness.mode` and `freshness.state`. The age in seconds (`age_s`) and the snapshot digest are **opt-in** (`--provenance`, §11), because either in the default page defeats prefix caching (PPE-3). **Status:** target; today both are in every default answer. Measured: both compared tools saw unstaged, untracked and staged edits and dropped reverted symbols; dctx's first query after a one-line edit costs a full re-index (core 7.48 s against 1.45 s warm; django 2.70 s against 0.82 s) until §19 lands. **Shipped behaviour (v1):** the modes above are a target. The CLI always takes a strict snapshot, so `freshness.state` is always `"verified"`; there is no stale flag (R3, §3). --- # Part III — Answers ## 10. The verbs ```text dctx map [TARGET] [OPTIONS] ``` | Verb | Use | Budget cap (tokens) | |---|---|---| | `map [TARGET]` | Outline a node or file (`--depth 1..3`) — landed; the project root, `p:`, `k:` and directory targets as a paged overview — **target, P1** (today refused or `gone`, TC-F05; the only overview is the unbounded legacy tree) | 2,000 | | `find TARGET` | Search names and concepts (`--kind`, `--in`) | 2,000 | | `neighbors TARGET` | Relations (`--edge`, `--dir in\|out\|both`, `--depth 1..4`) | 2,000 | | `explain TARGET` | One node's details: signature, doc line, edges summary | 1,000 | | `read TARGET` | Exact source (`--lines A-B`, `--full` up to 400 lines, `--level`) | 2,000 | | `grep PATTERN` (target, P1) | Literal or simple-glob text search over authorized files under the same ignore rules, grouped by enclosing symbol id, budgeted, paged (today: no text search; config-key questions scored 0/14) | 2,000 | | `status` (target) | Freshness, generation, policy digest; reads the manifest only; ≤50 ms | 200 | Paging uses an opaque `next` cursor, never offsets. Every page ends with a next-step hint. Planned additions: `dctx map plan` (budget planner, §12.5), `dctx blast` (§25), `dctx check` (§26). **Degradation (target, P1).** A budget below the smallest full record MUST return ids only, then `more`/`next`, never exit 1 (today 35 of 84 small-budget requests fail with "budget too small", TC-F09). **Concept queries (target, P1).** `find` tokenizes the query and identifiers on case, `_`, `-` and whitespace and ranks by token overlap with names, paths and `summary`; today multi-word queries return no records (0 of 7 concept questions, TC-F10). ## 11. Page formats and byte stability Two formats: the **text page** (default; one record per line; ids first) and **JSON v2** (`--json`; no insignificant whitespace; LF-terminated; field order fixed). Both obey: - no timestamps, snapshot digests, absolute paths, process ids, random values or locale-dependent text in the default output; provenance (snapshot digest, generation, age) is a **trailer line** behind `--provenance`, or a JSON field behind `--json --provenance` (P0 header prerequisite measured on 2026-11-06: all 33 tested text answers start with `# `; all 33 tested default JSON answers omit snapshot, generation and `age_s`, and are identical over five runs and after an unrelated comment edit. Shipped opt-in flag: `--meta`; the specified provenance trailer and `--provenance` interface remain target. [Evidence](research/stability-20261105/REPORT.md), TC-F03); - the text page carries content: `find` and `map` records are `idkindpath:L1-L2summary`; `explain` prints signature, summary and edge counts by kind; `read` prints the source span (P0 status, 2026-11-06: text `read` carried source in all three measured cases; text `explain` still printed only id/kind/path. Richer text fields remain target; [evidence](research/stability-20261105/REPORT.md), TC-F04); - JSON v2 omits `null` fields (target, P0: today thirteen keys per record, many null, so a JSON `find` fit 4 records where the text page fit 10); - canonical order (score desc, id asc; adjacency grouped by edge kind); - paths are root-relative with `/` separators on every OS; - the same request through CLI and library yields the same canonical page bytes. **Note (1.0.1, legacy source page).** The `dctx pack` / `dctx .` text page (the `[DCTX_LLM_CONTEXT_SNAPSHOT_V1]` envelope) follows the same no-timestamp rule by default: its tree and root lines carry the `ID` only, with no `MOD:` and no `SIZE:` (a size changes on every ordinary edit, and the tree precedes the file blocks), so a bare `touch` leaves the page byte-identical and an edit keeps the bytes before the edited file as a common prefix. `--tree-stamps=on` reproduces the 1.0.0 page with `MOD:` and `SIZE:` on every tree line; `{{{node.mod}}}` and `{{{node.size_part}}}` remain available to custom templates. **Gates.** (P0) ≥ 95 % of text answers byte-identical after an unrelated edit (0 of 63 today; comparison tool 59 of 70); JSON identical over 5 runs. (P1) The map page for a pinned tree is byte-identical on Linux, macOS and Windows and across thread counts. ## 12. Tiers, deltas, deduplication and compression levels ### 12.1 Prefix-stable tiers (target) Context that a host injects into a prompt is rendered as tiers, ordered from least to most volatile, each terminated by a fixed marker line: | Tier | Content | Changes when | |---|---|---| | T0 | Verb reference and conventions | dctx version changes | | T1 | Project outline (`map --depth 1`) | The outline changes | | T2 | Focus outline, relevant guardrails | The task changes | | T3 | Turn-local answers (`find`, `read`, …) | Every turn | Prerequisite: §11's header rule. Tiers cannot be prefix-stable while the first line of every answer names the snapshot. Invariant: a change confined to tier *k* never alters a byte of tiers < *k*. Policy `cache.breakpoints = ["T0","T1","T2"]` makes tier boundaries the cache breakpoints a host maps onto its provider's mechanism. **Gate:** rendered twice with a change in tier *k*, the common prefix length ≥ the byte offset of marker *k*; M7 ≥ 0.9 across turns on recorded traces. ### 12.2 View digests The provenance trailer (`--provenance`) names the answer's `view` digest (§5). A caller that keeps it can ask for a delta later. ### 12.3 Delta answers (target) `--since ` recomputes the answer and emits only records whose content digest changed, `-` lines for removed records, and a header `base= changed= removed= unchanged=`. An unknown base yields the full answer with `base=none`, never an error. The engine stores record ids and digests per view (not bytes) in a small, user-private, TTL-bound ledger. `dctx pack --since ` applies the same rule to whole files: unchanged files appear as one tree line with their digest. ### 12.4 Session deduplication (target) With `--session `, a record already emitted in the session renders as `=` unless its digest changed or `--full` is given. Session ledgers are per user, ≤1 MiB, ≤24 h. ### 12.5 Budget planner (target) `dctx map plan --budget N ` allocates a total budget by marginal value — named reads and explains first, then neighbors, then the find tail — and reports `planned`, `used`, `left`. Deterministic greedy over already-scored records. ### 12.6 Compression levels (target) `--level signature | skeleton | body` for `read` and for pack blocks: | Level | Content | |---|---| | `signature` | Declaration line(s) and the first sentence of the doc comment | | `skeleton` | Signature, nested declarations and control-flow keywords; bodies elided as `… N lines` | | `body` | The exact span | The level is part of the view digest. Defaults: map records use `signature`, `read` uses `body`; DTS MAY set levels per selection (for example `skeleton` for `tests/**`). ## 13. Token estimation The portable estimate is `ceil(2 × UTF-8 bytes / 7)` (landed). A host MAY supply an exact tokenizer through a port capability for budgeting; dctx never ships a tokenizer in the core. Reports always state raw bytes next to estimates. --- # Part IV — Policy ## 14. One language: DTS v2 The dctx Template System is the only configuration and policy language. DTS v1 templates keep rendering byte-identically. DTS v2 compiles typed sections into one sealed `ContextPlan` IR with per-section digests (`docs/design/contracts/DTS-v2.md`, `crates/dctx-template`). Every mode — pack, map, templates, cache, plugins, agent surfaces, learnings — consumes a compiled plan; there is no second, hidden policy path. | Section | Controls | Status | |---|---|---| | `SELECT` | Paths, languages, kinds; Include / Exclude / OmitContent / DebugVisible | contract | | `INDEX` | Requested facts, parsers, extraction limits (`max_facts_per_file`) | contract | | `BUDGET` | Bytes, tokens, records, depth, parse/memory/work bounds | contract | | `VIEW` | Pack, map and future projections; compression levels | contract | | `RENDER` | Partials, layouts, markers, bounded record iteration | landed (v1) | | `PLUGINS` / `PLUGIN` | Enablement, order, pinned versions and digests, grants, typed config | landed | | `POLICY` | Organization-wide ceilings (§15) | target | | `TENANT` | Named narrowing of an organization policy for a team or group | target | Example of one file controlling everything: ```ini [DCTX v2] [POLICY:acme] privacy.ignore += ["*.pem", "*.key", "secrets/", ".env*"] privacy.secret_classes = ["aws", "gcp", "ssh", "jwt"] telemetry = "none" freshness.min = "metadata_validated" cache.max_bytes = 1_073_741_824 cache.root_ttl_days = 14 budget.map.max_tokens = 1500 parsers.allow = ["syn", "structural", "opaque"] agents.hosts.allow = ["shell"] learnings.kinds = ["decisions", "guardrails"] learnings.max_bytes = 262_144 [PLUGINS:acme] enabled = ["dctx/git"] denied = ["dctx/ci-github"] network = "none" [PLUGIN:dctx/git] version = "1.0.0" digest = "sha256:…" allow = ["file.read:.gitignore", "file.write:.gitignore"] config.stage = false [TENANT:payments] languages = ["rust", "typescript"] budget.map.max_tokens = 1200 learnings.kinds = ["decisions"] ``` Compiler obligations: known keys only; `+=` only on append-only list fields; every value within the parent layer; an unknown section or field is refused; the compiler emits a digest per layer and the effective digest. The compiled artifact is the existing `DCTXIR` envelope with section kinds `POLICY = 16`, `TENANT = 17` (18–31 reserved). ## 15. The seven-layer policy lattice Today's rule — `effective_permission = host_grant ∩ organization_ceiling ∩ session_selection` (product contract C03) and the plugin grant lattice `M ∩ U ∩ O ∩ H ∩ S(t) ∩ A` — generalizes to seven layers. Each layer can only **narrow** the layers above it. | Layer | Written by | Signed by | Typical content | |---|---|---|---| | L0 built-in | The release | The release key | Hard caps (2,000 tokens, 8 MiB per file, 2 GiB cache), `network = none`, `telemetry = none` | | L1 organization | Security / platform team | Organization key (enrolled once) | Parser, plugin and agent-host allowlists; privacy rules; budgets; cache caps; learnings kinds | | L2 tenant | Team lead | Organization key or a delegated team key | Narrower languages, plugin set, default templates, budgets | | L3 machine | IT / device management | Machine key or a root-owned file | Cache root, offline mode, threads and memory, installer proxy | | L4 user | The developer | — (user-private file) | Personal defaults, consented plugins, installed agent hosts | | L5 project | The repository | Optional organization signature for "trusted project policy" | `.dctx/policy.dts`: selections, omit rules, templates, learnings location | | L6 session | The invocation | — | Flags, environment, library builder arguments | Rules: 1. **Monotone narrowing.** `effective = fold(narrow, L0 … L6)` per field: set intersection; numeric minimum; enums ranked toward the most restrictive; booleans AND for permissions and OR for `required` / `deny`. **A widening attempt is a typed compile error** naming the layer and field — never a silent clamp. 2. **Unreadable policy refuses.** A present bundle that fails verification blocks every mode except `dctx policy explain`. 3. **Policy epoch.** The effective digest is part of `ViewKey` and of every plugin admission; any layer change invalidates cached authorization before serving. 4. **Tenants.** A tenant is a named narrowing selected by L3 or L4, or requested by a project from those the organization lists. A project cannot invent a tenant. **Property P9 (monotone policy).** For random layer stacks, the effective value is within every layer field-wise, and a widening at layer *k* fails naming *k*. Mutation witness: removing the intersection makes the property fail. ### 15.1 Locations | OS | L3 machine | L4 user | L1/L2 organization bundles | |---|---|---|---| | Linux | `/etc/dctx/policy.d/*.dts` | `${XDG_CONFIG_HOME:-~/.config}/dctx/policy.dts` | `/etc/dctx/org/*.dctxpol` | | macOS | `/Library/Application Support/dctx/policy.d/` | `~/Library/Application Support/dctx/policy.dts` | `/Library/Application Support/dctx/org/` (MDM-deployable) | | Windows | `%ProgramData%\dctx\policy.d\` | `%APPDATA%\dctx\policy.dts` | `%ProgramData%\dctx\org\` | | Project | `.dctx/policy.dts` | | | `$DCTX_ORG_POLICY` MAY point at a bundle. The library never discovers locations itself; the CLI and desktop pass them explicitly (product contract C01). ## 16. Organization bundles, signing and enrollment A `.dctxpol` bundle reuses the plugin offline-bundle container (bounded table of named payloads with lengths and digests; no compression, no links): `policy.dts`, `tenants/.dts`, `trust/keys.json`, `manifest.json`, `manifest.sig`. The signature is Ed25519 over `dctx-org-policy-v1 ‖ manifest bytes`, verified by `crates/dctx-ed25519`. - **Enrollment.** `dctx policy enroll --fingerprint ` pins the organization key once, interactively. - **Updates.** A monotonic `sequence` is accepted forward only; downgrades are refused; a revocation list is honored. These mechanisms already exist for plugin distribution. - **Distribution** is any file channel: MDM, configuration management, a repository the organization controls, or the installer's own download. dctx itself fetches nothing. ## 17. Explain and receipts - `dctx policy explain [field]` prints each effective value, the layer that set it and the signer fingerprint. Byte-stable. - Every operation records the effective policy digest, the per-layer digests and signer fingerprints in the local, user-private receipt log. `dctx policy receipts --since ` lists them. Nothing is uploaded. --- # Part V — Index ## 18. Segments, manifests and the per-file fact store The index is a set of immutable, checksummed segments (`docs/design/contracts/SEGMENTS-v1.md`, `crates/dctx-map-segment`, `crates/dctx-adapter-store`) under the cache root. No SQLite, no daemon. ```text /v2// facts//.seg per-file fact segments; a changed file reparses one segment views//view.seg nodes, forward and reverse adjacency, postings, dictionary views//manifest.man sorted path -> (stamp, ObjectKey, FactKey) current.ptr atomic pointer to the published generation answers/.ledger delta and dedup ledger (§12.3–12.4) ``` - Identical files parse once across roots (shared `FactKey`). - Publication uses a writer lock, staging, pointer swap, leases and a previous pointer for recovery (landed protocol; formal model in `docs/formal/dctx-cache`). - Cache lifecycle: time-based expiry, a size cap and a bounded automatic cleaner (landed defaults: 7 days idle overlays, 30 days unpinned roots, 2 GiB hard cap). - Readers validate section checksums lazily on first touch; the envelope checksum is mandatory at publication. - Generations are content-addressed: an unchanged snapshot digest publishes no new bytes (today three byte-identical 158 MB generations of one root were stored). Superseded, unpinned generations of the same root are reclaimable at the next invocation; the unlink grace period applies to orphaned objects, not to superseded generations (today a one-day grace let a root grow from 158 MB to 946 MB while `cache gc --dry-run` reclaimed 0 bytes, TC-F02). ## 19. Freshness check and incremental rebuild **Status: target, not implemented.** The shipped engine has no stamp-only pass, overlay or per-file rebuild: each process re-walks and re-hashes, and any change rebuilds fully (R3, §3). 1. **Stamp pass.** Walk the inventory (names, sizes, mtimes; excluded directories are never entered) and compare with the manifest's sorted path table. 2. **Digest pass** only for entries whose stamp differs, plus the query's dependency scope under `strict_live`. `read` always verifies its own bytes. 3. **Rebuild.** Changed files reparse one fact segment each; their nodes and edges are masked by an overlay; references that named symbols they declare (or now declare) are re-resolved through the reverse unresolved-name index; the result publishes as an overlay generation. Overlays compact into the base past a threshold. An unchanged snapshot digest reuses the published generation without writing. | Gate | Target | Measured today (§31.0) | |---|---|---| | `dctx map status` | ≤50 ms p95 | no verb | | Warm `find` / `neighbors` / `read`, small and medium corpora | ≤30 ms engine p95, ≤80 ms process | 0.03–0.26 s process (comparison 0.69–1.40 s) | | Warm `find` / `neighbors` / `read`, largest corpus (core, 3,190 files) | ≤0.8 s process, ≤150 MiB | 1.45 s, 370 MiB (comparison `callers` 0.83 s) | | First query after a one-line edit | ≤2× warm | ≈ cold (core 7.48 s against 1.45 s warm; django 2.70 s against 0.82 s) | | Cache per root after 10 edits | ≤1.5× one generation | 6× (158 MB -> 946 MB after about five edits) | | Single-file reindex | ≤50 ms | n/a | | Correctness | Answers byte-identical to a cold rebuild | — | ## 20. Cold build Parallel parsing with a bounded parser thread pool (`std::thread::scope`, ≤ available parallelism); each thread owns its fact segments; a single sealer merges sorted outputs and hashes incrementally without materializing a joined payload. Policy caps facts per file (`extraction.max_facts_per_file`, default 10,000); excess configuration and JSON leaves collapse into one `partial` module node. **Gate:** cold build ≤5 s and peak RSS ≤150 MiB on the pinned corpus; persistent bytes ≤40 MiB. Measured today (§31.0): core (3,190 files) 6.05 s / 567 MiB; django (7,071 files) 2.48 s / 92 MiB; flask (235 files) 0.09 s / 8 MiB. Cold indexing is 2.8 to 69 times faster than the comparison tool on all seven corpora with 1.6 to 27 times less peak memory, and MUST stay at or below half of its time per corpus. ## 21. Ranking Lexical scoring over identifiers split on case and separators, path segments and the first doc line; exact-name boost; kind and path filters; confidence-aware boosts for graph neighbors of the focus set. Integer scores; ties broken by id; the scoring revision is versioned and part of the view digest. --- # Part VI — Extension ## 22. Core, surface or plugin: the decision procedure ```text Does it read or write anything other than authorized source bytes, the dctx cache root or a caller-supplied sink? no -> core: engine or adapter (first-party crate, std-only target) yes -> does it only transport answers the core already produced, deciding nothing about content? yes -> surface adapter (compiled in behind a feature: CLI, hook-file generator) no -> plugin (out of process, brokered, consented, receipted) Does it need a socket, a subprocess or a foreign runtime (language server, compiler, model)? yes -> plugin; never core; never a default-on effect Does it change selection, identity, freshness, ranking or budgets? yes -> refused as a plugin capability ``` | Component | Placement | |---|---| | Ids, spans, budgets, selection, digest, DTS compiler, segment codec, resolver, binder | Pure core | | 13 lexer crates covering 15 language variants (Rust, JS, TS, TSX, Markdown, Python, Go, Java, C/C++, JSON/TOML/YAML, C#, Kotlin, Ruby, PHP, Swift); `syn` adapter | Core engine | | Filesystem source, cache, segment store | Adapters | | CLI, agent-hook generator, statusline | Surfaces | | Git (`.gitignore` protection, staging, `vcs.changes`) | First-party plugin (bundled) | | Language-server / SCIP edges | First-party plugin, edge overlay | | CI and pull-request comments | Plugin with the v2 network capability | | Telemetry | Does not exist | | Model calls | Never in dctx; summaries only by fingerprint-bound import | ## 23. Plugin protocol and its v1.x extensions The plugin host is landed: a grant lattice with explicit denies, policy epochs with re-checks at admission and commit, receipts and a ledger, liveness by progress (not timers), signed distribution with pinned keys and revocation, Linux confinement, and TLA+ models with mutation witnesses (`docs/design/PLUGINS.md`, `docs/formal/dctx-plugins`). Properties PP1–PP10 hold for every extension below. ### 23.1 New capabilities and hooks (target, negotiated minor versions) | Addition | Kind | Contract | |---|---|---| | `vcs.changes {scope: staged \| worktree \| range}` | Broker request (git plugin) | Bounded `{path, added, removed}` hunks; paths filtered by current selection | | `facts.overlay {generation, segment}` | Broker request (overlay plugins) | Uploads an edge-only overlay segment with provenance; the host checks every endpoint exists and no row touches an excluded path; never merged into fact segments | | `after-query` | Advisory hook | Verb, record ids, bytes and budget use — never record contents | | `on-source-changed` | Advisory hook | Fired when a generation publishes; payload is the changed path list after selection | | `network.post {origin, max_bytes}` | Capability (protocol v2) | Separate consent, organization egress allowlist, receipts with response digest; off in every default | ### 23.2 The compiler-grade overlay (`dctx/lsp`, `dctx/scip`) Spawns a configured language server under confinement (no project writes, no network), asks for definitions and references of the view's `name`-confidence and unresolved references in bounded batches, and uploads an edge overlay labeled `exact (lsp:@)`. `--no-overlay` disables it per request. SCIP import is the batch variant for CI. Neither is a default; neither changes `FactKey`. ## 24. Surfaces ### 24.1 CLI One binary: `dctx` (pack, map, template, cache, plugin, policy, agent, learn, check, blast). Interactive TUI when run without arguments. ### 24.2 Library facade `crates/dctx` is the stable API for every surface (`docs/design/contracts/API-PORTS-v1.md`). Bindings for Python, Node and a C ABI wrap the facade; none re-implements an engine. ### 24.3 Agent hooks (target) `dctx agent install [--project]` renders, from the effective policy, the host's own configuration fragment: a statusline that runs `dctx map status`, a session-start injection of tiers T0–T2 (≤1,000 tokens, placed after the host's stable prompt prefix), and the guidance "use `dctx map find` / `read` before grep and cat". Installation is a user-consented file write with a receipt, idempotent (marker line) and reversible (`dctx agent uninstall`). Organization policy can allow, require or forbid hosts. No daemon, no watcher. ### 24.4 Desktop The desktop app is **free, forever**. It is a surface over the same facade: snapshots, settings, recent projects, plugin management. It has no engine or cache behaviour of its own and is never part of the CLI or library dependency closure. ## 25. Blast radius (target) `dctx blast` traverses reverse adjacency (callers, implementors, tests, documents) from a set of changed spans, bounded like `neighbors`. The graph side is core. The change side has two sources, neither of which puts a VCS in the core: 1. **Snapshot diff (default).** `dctx blast --from ` compares the current source snapshot with a retained one. Works in any directory. 2. **VCS supply.** The git plugin's `vcs.changes` returns hunks for `--staged`, `--branch ` and similar; the core maps hunks to node spans. Formats: text records, JSON, and `--format pr-comment` (Markdown). Posting the comment is a network plugin. **Gate:** ≤100 ms warm for a 10-hunk change on the pinned corpus. ## 26. Learnings (target) Teams lose decisions and guardrails to chat logs. dctx keeps them as plain files next to the code, without becoming a memory product. | Aspect | Rule | |---|---| | Location | `.dctx/learnings//.md`; kinds `decisions`, `guardrails`, `preferences`, `skills`; policy may narrow kinds and size | | Format | Markdown; first heading is the title; a fenced `dctx` block with `applies:` ids, `since:` snapshot, `status: active \| retired`, optional `enforce: true` | | Indexing | Ordinary `d:` doc nodes with `documents` edges to the ids they name; `find --kind learning`; boost when `applies` meets the focus set | | Authoring | `dctx learn add "" [--applies <id>…]`. The core writes only into `.dctx/learnings/` and only on an explicit user action | | Sharing | It is content: shared through version control like any file; the git plugin may stage it when granted | | `dctx check` | For each changed node (§25), lists guardrails whose `applies` covers it or its neighbors at depth 1. Advisory; exit non-zero only with `--strict` and an enforced active guardrail | | Freshness | A learning that applies to a `gone` id is reported `orphaned`; nothing is deleted automatically | | Model-written text | Only via `dctx learn import` with body-fingerprint binding; labeled `src=import:<tag>`; served only while fingerprints match | --- # Part VII — Assurance ## 27. Dependencies and build profiles All first-party code and documentation are Apache-2.0, copyright Eris Margeta, including the desktop app and planned GPUI rebuild. This section records build engineering goals, not an edition, license tier or certification of suitability. The current dependency inventories are [THIRD_PARTY.md](../THIRD_PARTY.md) and [THIRD_PARTY_NPM.md](../THIRD_PARTY_NPM.md); inspect manifests and features for an exact build's closure. Earlier 0.25.0 dependency counts are historical measurements. ### 27.1 The rules - **Core crates are std-only.** `dctx-hash`, `dctx-core`, `dctx-ports`, `dctx-map-model` (without `wire-json`), `dctx-map-segment`, `dctx-template`, `dctx-pack`, `dctx-map-resolve`, `dctx-map-bind`, `dctx-plugin-protocol`, the hand-written lexers, `dctx-adapter-fs`, `dctx-adapter-store`, `dctx-adapter-cache` and `dctx-map-scan` have zero third-party normal dependencies and forbid `unsafe`; CI checks `cargo tree -e normal` per crate. - **Every third-party crate in a default build is listed** in `docs/DEPENDENCIES.md` with version, licence, `unsafe` count, reason and the plan for it. CI fails if the closure grows beyond the list. - **Ed25519 stays for security and trust.** `ed25519-dalek` (exact pin, `std` feature only, verify-only) is a vetted, widely audited security crate and the **single disclosed exception** to the zero-third-party rule, behind feature `trust`. It verifies the signatures on plugins and organization policy bundles. A build without `trust` has no third-party crate and cannot verify signatures; it refuses unsigned bundles rather than trusting them. Audited cryptography is not replaced by something less proven; the search for the best long-term solution continues, and any successor must clear the same bar (RFC 8032 and Wycheproof vectors, differential fuzzing, independent review). ### 27.2 Planned removals | Remove | First-party replacement | Gate | |---|---|---| | `syn` from the `strict` feature | Today `strict` implies `syntax-rust`; a minimal feature set MUST NOT (structural Rust extractor with `precision.parser = dctx-structural/1`) | Build proves the closure | | `serde`, `serde_json`, `thiserror`, production `sha2` | The facade's hand-written canonical JSON; std `Error`; `dctx-hash` | Goldens byte-identical | | `rusqlite` and bundled SQLite | The immutable segment index (§18) | Segment index beats the SQLite baseline on two of latency, disk and refresh with no quality loss | | `syn` stack from the default build | First-party Rust structural extractor + binder (§7.1) | Held-out precision ≥ `syn` − 1 point; zero wrong `exact` edges | | Linux confinement crates | Kept as a disclosed, target-specific adapter dependency outside the minimal closure (plugins unavailable in that build), or a reviewed first-party syscall boundary in `dctx-plugin-platform` | Confinement property tests; written `unsafe` review | The desktop app is a separate surface over the facade and is never part of the CLI or library closure. ### 27.3 Maintenance dctx is Apache-2.0 open source, including the desktop app, with no license fee. Organizations that depend on dctx can sign a maintenance agreement for security response targets, long-term support and priority work; see [MAINTENANCE.md](../MAINTENANCE.md). Build-closure targets are engineering goals. ## 28. Conformance suite | Suite | What it proves | |---|---| | Verb goldens (`docs/design/contracts/GOLDEN-REQUESTS-v1.json`) | Byte-identical pages across OS, thread count and surface | | Property tests P1–P9 | Privacy, publication, recovery, determinism, bounds, policy monotonicity | | Defect corpus R1–R10 | Each RAG defect class is absent, with a positive control per class | | Edge corpus | Precision and recall per language and confidence rung (§7.1) | | `dctx bench tokens` | M1–M7 from recorded traces (plain JSONL from the host); dctx never contacts a provider | | Cross-tool benchmark | The isolated, pinned protocol in `docs/research/trail-code-2026-10/` (seven corpora and one adversarial, 140 targets, 70 questions, stability, freshness, adversarial, network audit). Rerun at every phase gate; numbers in §31.0 | Published numbers MUST come from these suites with pinned corpus digests. ## 29. Formal models TLA+ models with mutation witnesses cover the cache lifecycle (`docs/formal/dctx-cache`) and the plugin host (`docs/formal/dctx-plugins`). New models are required for the policy lattice (P9) and for delta and dedup ledgers (no record lost, none duplicated across a base change). ## 30. Versioning and compatibility Independent version axes: library API, wire format (text page, JSON v2), DTS source, plan IR, identity, segments, cache layout, plugin protocol, policy bundle. Each axis has a major/minor rule; readers refuse unknown required sections; a version declaration selects behaviour — it is never inferred from an unknown field. --- # Part VIII — Delivery ## 31. Roadmap and acceptance gates ### 31.0 Measured baseline dctx `17dff0b` (`dctx-cli v0.25.0` development line) against Trail-Code 0.23.1 on seven pinned corpora (flask, ripgrep, pocketbase, trailcode, dctx, django, core) and one generated adversarial corpus; Linux, eight pinned CPUs, isolated network namespace; full method, raw data and scripts in `docs/research/trail-code-2026-10/`. Every gate in this section names the row it must move. | Measure | dctx | Trail-Code | Source | |---|---|---|---| | Call-graph precision / recall (callers, depth 1; 140 definition targets) | — / 0.00 (no call or import edges emitted) | 0.94–1.00 / 0.10–0.96 per corpus | report §7, `data/accuracy.csv` | | Recall by category: hub / rare / receiver / collision / interface | 0 / 0 / 0 / 0 / 0 | 0.42 / 0.93 / 0.56 / 0.86 / 0.42 | `data/accuracy_by_category.csv` | | Definition ranked first (`find` against `ask`) | 103 of 140 | 79 of 140 | report §7 | | 70 agent questions: score / facts / estimated tokens | 69 of 140 · 169 of 354 · 500,005 (480k from the unbounded legacy tree) | 122 of 140 · 312 of 354 · 88,691 | `data/tasks.csv` | | Facts per 1,000 tokens, excluding the overview question | 7.15 | 4.98 | report §8 | | Question types (score of 14): config key / concept / callees / impact / definition+callers / collision | 0 / 0 / 2 / 7 / 7 / 6 | 14 / 12 / 8 / 13 / 10 / 12 | report §8 | | Cold index, seven corpora: wall / peak RSS | 0.09–6.05 s / 8–567 MiB | 2.44–94.89 s / 181–2,111 MiB | `data/indexing.csv` | | Warm `find`: small and medium corpora / largest corpus (core) | 0.03–0.26 s / 1.45 s | 0.69–1.40 s / 1.65 s (`callers` 0.83 s) | `data/queries_warm.csv` | | First query after a one-line edit: core / django | 7.48 s / 2.70 s | 5.45 s / 11.30 s | `data/freshness.csv` | | Cache growth after about five edits (core) | 158 MB -> 946 MB; `gc --dry-run` reclaimed 0 bytes | constant 65 MB | report §6 | | Text answers identical after an unrelated edit | Historical: 0 of 63 (`17dff0b`); 2026-11-06: 33 of 33 (`0495f5f`, three pinned local corpora, unrelated comment edits); JSON 33 of 33, also identical over five runs; paired-answer M7 = 1.0 | Historical: 59 of 70 (not rerun) | Historical: `data/stability.csv`; [new CSV](research/stability-20261105/stability.csv), [protocol and limits](research/stability-20261105/REPORT.md) | | Budget cap honoured | 2,000-token cap never exceeded (worst answer 6,996 bytes); 35 of 84 small budgets fail with exit 1 | no cap; one answer 142,197 bytes | report §13 | | Install footprint | one 9,207,072-byte binary | 405,601,700 bytes of `node_modules` plus Node | report §3 | | Sockets in audited runs | 0 | 30 in a daily update check that ignores the documented opt-out | report §11 | | Repository writes in map mode | none | `.gitignore` modified and `.ignore` added on every build | report §4 | | Gitignored secret with no `.git` present | excluded | indexed | report §10 | | Non-ignored `.env` in `pack` / `build` | **printed by `pack`** | never read | report §10 | Where dctx answered, it was the terser tool; where it scored lower, the answers were empty or thin (no edges, id-only text pages, no bounded overview, no text search, no multi-word search). The roadmap below closes those holes first, with code that already exists, before the architectural work. ### 31.1 Phases All gates are measured by rerunning the benchmark scripts on the same pinned corpora and gold; values in parentheses are today's (§31.0). E1 and E2 run in parallel with P0–P4 because they touch `crates/dctx-template`, manifests and CI, not the index. | Phase | Scope | Acceptance (all must hold) | |---|---|---| | **P0 Close the holes** (§4 item 3, §7, §11) | Wire reference resolution into the facade index; text pages carry content; provenance moves to an opt-in trailer; secret-shaped omit defaults | `neighbors --edge calls --dir in` non-empty on ≥ 120 of 140 targets; precision (`exact ∪ name`) ≥ 0.95; recall ≥ 0.88 on *rare* (comparison 0.93), ≥ 0.81 on *collision* (0.86), ≥ 0.35 on *hub* (0.42), ≥ 0.25 on *receiver* (0.56); zero wrong `exact`. Text answers identical after an unrelated edit ≥ 95 % (0 of 63); JSON identical over 5 runs. Task score ≥ 95 of 140 (69). The adversarial `.env` value absent from `pack` output; path listed | | **P1 Answer the questions agents ask** (§8, §10) | Bounded overview for `map` without a target, `p:` and directory targets; `grep`; `find` tokenization; small budgets degrade; omission counts in `precision` | Overview question 14 of 14 with ≤ 15,000 tokens over seven corpora (480,000); config-key ≥ 12 of 14 (0); concept ≥ 10 of 14 (0); every budgeted request returns a page (35 of 84 failed); task score ≥ 115 of 140 at ≤ 100,000 tokens (comparison 122 at 88,691); M8 ≥ 0.80 (0.48) | | **P2 Persistent incremental index** (§18–20) | Per-file fact segments keyed by `FactKey`; content-addressed generations; superseded same-root generations reclaimed at the next invocation; two-level freshness; lazy per-section loads; parallel cold build; per-file fact cap; `status` | First query after a one-line edit ≤ 2× warm on every corpus (core 7.48 s -> ≤ 3.0 s; django 2.70 s -> ≤ 1.7 s); cache per root ≤ 1.5× one generation after 10 edits (946 MB -> ≤ 240 MB); `gc` reclaims superseded bytes; warm queries on core ≤ 0.8 s and ≤ 150 MiB (1.45 s / 370 MiB; comparison 0.83 s); cold core ≤ 5 s / ≤ 150 MiB (6.05 s / 567 MiB); cold time ≤ 0.5× comparison on every corpus; `status` ≤ 50 ms | | **P3 Binder** (§7.1) | `dctx-map-bind`: scope graph, per-language import resolution from lexed manifests, receiver-type rules, `typed` rung, edge corpus | Receiver recall ≥ 0.56, interface name-level ≥ 0.42, hub ≥ 0.42; `exact ∪ typed` precision ≥ 0.95; zero wrong `exact`; callees question ≥ 10 of 14 (2) | | **P4 Token economics** (§12) | Tiers T0–T3, view digests, `--since` deltas, session dedup, compression levels, planner, `dctx bench tokens`, agent seeding | M7 ≥ 0.9 across turns; on ≥ 30 accepted tasks per route: M2 −50 %, M1 −25 %, M3 −50 %, M4 unchanged; task tokens ≤ 0.8× comparison at M8 ≥ 0.85; M6 reported | | **E1 Organization control** (§14–17; parallel) | `POLICY` / `TENANT`, seven layers, `.dctxpol`, enrollment, explain, receipts | P9; one bundle demonstrably controls every mode; an unverifiable bundle refuses | | **E2 Minimal build profile** (§27; parallel) | Removals in §27.2; `docs/DEPENDENCIES.md` with CI diff; truthful `--version`; version strings matching the actual release or development version | `cargo tree -e normal` for a minimal feature set lists only `dctx-*` crates and the Ed25519 verifier closure behind `trust`; the `strict` feature no longer implies `syn` | | **P5 Surfaces** (§24–26) | Agent hooks, `blast`, learnings and `check`, `vcs.changes` | Hooks idempotent with receipts; `blast` ≤ 100 ms warm | | **P6 Overlays and D3** (§23.2, §27.2) | LSP and SCIP overlays; network capability; CI comment plugin; first-party Rust structural extractor replaces `syn` in the default build | Overlays never alter first-party facts; PP1–PP10 still modeled; `syn` removed only at corpus parity | P0 and P1 turn a 69-of-140 tool into a ≥ 115-of-140 tool with changes measured in days, using lexers and a resolver that already exist. P2 is the one architectural piece, and it is also where dctx loses to the comparison tool on the largest corpus. P3 is the comparison people will make next. P4 pays only once answers are complete and stable. E1 and E2 are engineering targets for organization policy and a reduced dependency closure. They do not introduce a paid edition or certify production readiness. ## 32. Non-goals | Not doing | Why | |---|---| | Embeddings or a vector index in the core | Non-deterministic, model-dependent, hides provenance (R2, R8) | | Calling a model from the engine | Breaks determinism; adds model calls outside the context engine contract | | A daemon or file watcher | One binary, no runtime; a per-invocation stamp check meets 50 ms | | VCS in the core | Privacy and dependency reasons; everything needed is a plugin or dctx's own snapshot diff | | A second configuration language | Two policy engines diverge; DTS already compiles to a sealed IR | | Telemetry, even opt-out | Trust is the product | | A hosted index or SaaS | Changes the threat model | | Parser injection or selection override by plugins | Would make identity and privacy unverifiable | | Chasing language counts | 13 lexers covering 15 language variants, each with precision labels, beat 23 with silent errors (the comparison tool indexed 8 of 13 planted extra-language files; dctx indexed none and said so); each new language needs a held-out corpus | | mmap or FST before measurement | Requires a ≥20 % measured gain first | | In-band agent instructions in answers | Tool output is data; a banner costs tokens on every call and changes with the covered files | --- # Appendix A — Lineage | Year | Generation | What it solved | |---|---|---| | 2025 | **dircontxt**, pure C (v1.0.0, 15.11.2025; `legacy-c/`) | Give a model the whole project without pasting forty files: one structured `.llmcontext.txt`, a binary state file, version-aware snapshots and diffs, a three-tier ignore hierarchy, global configuration. Zero dependencies. | | 2026 | **dctx**, Rust | Same privacy promise (ignored files never opened), pack diffs, the template system, the plugin host, map mode for agents, the cache lifecycle, the desktop app | | Next | **dctx 1.0** (this specification) | One engine and one policy for every workflow, from hand-coding to software factories, measured by prompt-processing efficiency | # Appendix B — Comparison with Trail-Code The isolated, reproducible head-to-head is in [`docs/research/trail-code-2026-10/REPORT.md`](research/trail-code-2026-10/REPORT.md). Summary of the design difference, independent of the measurements: | | dctx | Trail-Code | |---|---|---| | Runtime | One Rust binary; std-only core; zero third-party crates in the tagged 0.25.0 `dctx-core`/CLI; 46 in the development line (§27) | Node.js package with an npm dependency tree (405.6 MB) | | Network | None in the core; no telemetry; 0 sockets in every audited run | Telemetry on by default (opt-out); daily update check not gated by the opt-out; writes `.gitignore`/`.ignore` on every build | | Agent interface | CLI verbs today; hooks are planned surfaces (§24) | Hooks, statusline | | Call precision | Lexers and resolver landed; edges not emitted by the shipped CLI (P0); `typed` rung planned (§7.1) | Scope-aware resolution with receiver typing for several languages; optional language servers | | Measured | §31.0 | §31.0 | | Organization control | Signed seven-layer policy (§15–16) | Not specified | | Team memory | Plain-file learnings, policy-governed (§26) | Learnings shared through git | | Output contract | Bounded, deterministic, precision-labeled pages | Token-budgeted map; signature views | # Appendix C — Reserved names Id prefixes `m:`, `s:`, `d:`, `k:`, `p:`, `@`; DTS section kinds 16–31; plugin namespace `dctx/`; file names `.dctx/`, `.dctxignore`, `.dctxpol`; environment variables `DCTX_*`. # Appendix D — Document map | Topic | Document | |---|---| | Accepted architecture decisions | `docs/design/ARCHITECTURE-DECISIONS.md` | | Product contracts C01–C11, properties P1–P8 | `docs/design/PRODUCT-CONTRACTS.md` | | Versioned contracts | `docs/design/contracts/` | | Plugin system | `docs/design/PLUGINS.md`, `docs/design/plugin-api/` | | Map-mode user guide | `docs/guides/MAP-MODE.md` | | Crate inventory | `docs/CRATE-MAP.md` | | Formal models | `docs/formal/` | | Head-to-head benchmark and raw data | `docs/research/trail-code-2026-10/` | | Original map-mode design (historical) | `docs/SPEC-MAP-MODE.md` | </FILE_CONTENT_END ID="F020"> <FILE_CONTENT_START ID="F021" PATH="docs/START.md" LINES="230"> <!-- SPDX-License-Identifier: Apache-2.0 --> <!-- SPDX-FileCopyrightText: 2026 Eris Margeta --> # What dctx is dctx turns any folder into the smallest correct context for a task, offline, with byte-stable output that prompt caches can reuse. “Smallest correct context” describes the goal, not a proof that task selection is complete or minimal. The shipped engine selects lexical symbols and document sections, verifies source reads and bounds answers. A 200 GB folder needs a relevant sub-root and ignore rules; output budgets do not bound scanning. Byte stability enables reuse, while provider cache rules determine actual hits. dctx has no embeddings, network, telemetry or agent loop in its pack/map workflows. It does not call a model or execute the task for you. > dctx is an advanced tool with several ways to use it. Used well, it cuts irrelevant text from selected tool answers. It does not save tokens by default; savings depend on a system reusing byte-identical, prefix-stable context. Extra calls can add tokens. If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything. ## Choose your path Choose one of these four paths. Each starts with a shipped workflow; the planned scope and distribution features are labeled explicitly. 1. [One giant folder](#one-giant-folder) 2. [Many small projects](#many-small-projects) 3. [Agent builder embedding a library](#agent-builder-embedding-a-library) 4. [Team / enterprise admin](#team--enterprise-admin) ### One giant folder One giant folder (e.g. 200 GB): system binary; per-root ignore policy; name a sub-root/--place in tasks. Pitfall: pointing agents at the whole root. Install the [system binary](#safe-path-in-ten-minutes), choose a relevant package, and put exclusions in that root's `.dctxignore` before the first query: ```sh dctx map find Config --place packages/service-a --budget 500 --limit 5 ``` Expect bounded symbol IDs and line ranges, not a complete answer about the whole parent tree. Use an ID with `map read`. There is no general receipt yet; `--json` exposes freshness, precision and pagination. Each invocation checks source stamps; no daemon or file watcher is used. Catalog-first sharding and a unified policy file are planned. Read the [huge-tree limits and ignore example](MODALITIES.md#huge-trees-scope-before-indexing) before warming an index; `--in` only filters after indexing. ### Many small projects Many small projects: system binary; CLI commands from each project root; no project dependency. Pitfall: stale caches of deleted projects -> cache gc/purge. Install one binary on PATH and use it from a shell or your agent's shell tool. Run commands from the intended project root. No project dependency is required. Start with `dctx map find`, then `dctx map read` using its exact ID. Expect source plus freshness and precision in JSON, not a general receipt or session delta. ```sh dctx cache status --json dctx cache gc --dry-run dctx cache purge --root /absolute/deleted-project --dry-run ``` Inspect the dry run before applying cleanup; `purge` requires `--yes`. See [cache controls](guides/MAP-MODE.md#index-cache-and-privacy). Indexes live in an engine `major.minor` subdirectory (for example `1.3`) of the cache parent, which is `DCTX_CACHE_DIR` or the platform default `v2` cache root; patch releases share it, and data from other engine versions is ignored. ### Agent builder embedding a library Agent builder embedding a library: project library with its own pinned binary (Python, Node or Go wrapper over `dctx rpc`); never parse or slice pack text. Pitfall: re-implementing engine logic. The [Python](../packages/python/README.md), [Node](../packaging/npm/dctx/README.md) and [Go](../packages/go/README.md) wrappers over `dctx rpc` are built and tested in CI. Install Node with `npm install @tejl/dctx`, which includes a pinned `@tejl/dctx-<platform>` optional dependency; use CI artifacts or a checkout for Python and Go as their READMEs describe. Alternatively, pin the [Rust facade](MODALITIES.md#rust-library-embed-the-facade) from tagged Git, or invoke the installed CLI as a subprocess. The first runnable Rust example is in the [library doctest](../examples/library/README.md). For subprocess use: ```sh dctx map find Config --json --budget 500 --limit 5 ``` Expect JSON records with IDs and precision/freshness metadata; pass a returned ID to `map read --json` for `source_utf8`. Keep engine selection and rendering in the engine. Pass opaque continuation cursors back unchanged rather than slicing pack text. [Named context](CONTEXT.md) adds stable chunk IDs and opt-in delivery sessions: use `dctx context TARGET --session ID --dedupe`. Delivery history lasts for the CLI invocation or RPC connection; general receipts remain planned. A Rust facade `Session` is an in-process API object. See the [scope contract](#two-scopes-one-binary). ### Team / enterprise admin Team / enterprise admin: system binary via package manager, signature + SBOM verification, one pinned version fleet-wide. Pitfall: mixing project and system versions without checking (`dctx doctor`). This is the rollout target. Today, pin a release archive and check its matching `SHA256SUMS` entry; package-manager distribution, signed CLI binaries and a release SBOM verification workflow are planned. Deploy the verified archive and root ignore rules through your existing fleet tooling. Record the resolved binary path and start with: ```sh dctx --version --verbose ``` Expect version and feature/precision limits. `dctx doctor` lists the dctx binaries visible from a directory with their scopes and SHA-256 checksums; signature-status output is planned. Check paths and versions explicitly during onboarding; use [release procedure](../RELEASING.md), [testing](TESTING.md) and [security reporting](../SECURITY.md) for the current controls. Signed organization policy bundles and audit journals are planned. ## Safe path in ten minutes ### 1. Install the system binary Download the archive for your OS and architecture and `SHA256SUMS` from [GitHub Releases](https://github.com/Eris-Margeta/dctx/releases/tag/v1.3.1). Compare the archive's SHA-256 with its matching entry before extracting it. On Linux use `sha256sum ARCHIVE`, on macOS `shasum -a 256 ARCHIVE`, or on Windows PowerShell `Get-FileHash ARCHIVE -Algorithm SHA256`, replacing `ARCHIVE` with the downloaded filename. This checks integrity against the release checksums; signed binary verification is planned. Extract the archive and put `dctx` (`dctx.exe` on Windows) on your user `PATH`. Archives cover Linux x64/ARM64, macOS x64/ARM64 and Windows x64. ```sh dctx --version ``` Use the system binary for interactive agents. Project wrappers are available through npm for Node and CI artifacts for Python and Go; no project dependency is needed for this path. ### 2. Choose one project and inspect one answer Use a small project or a relevant sub-root. Check `.gitignore` and `.dctxignore` before scanning; leave `DCTX_INDEX_IGNORED` unset. From that directory: ```sh dctx map find Config --json --budget 500 --limit 5 ``` Replace `Config` with a symbol or heading in your project. Read a returned ID with `dctx map read 'ID' --json`. The JSON includes verified source bytes as `source_utf8` and reports precision, freshness and pagination. Keep the same root between calls, because root-relative IDs change when the root changes. ### 3. Use the CLI from your shell or agent Run from the selected project root: ```sh dctx map find Config --limit 5 --budget 500 dctx map read 'ID_FROM_FIND' --budget 2000 ``` Replace `ID_FROM_FIND` with an exact ID returned by `find`. Use the same commands through an agent's shell tool. See the [map guide](guides/MAP-MODE.md) for bounds and pagination, and [agent guidance](guides/AGENTS-SNIPPET.md) for shell usage. ### 4. Measure before changing anything Run the same small task with grep plus narrow file reads and with dctx CLI. Record task correctness, number of tool calls, startup instructions and schemas, all model input/output tokens, provider cache hits, latency and billed cost when available. Include the history carried into each model turn. Smaller tool answers alone do not establish whole-session savings. General receipts are planned. Today, retain JSON metadata and the agent's usage report. For task packs, the shipped footer is a useful output accounting line: ```sh dctx pack . --for 'Config' --budget 800 ``` It reports `body_tokens`, `budget` and `dropped`, using estimated tokens rather than a provider tokenizer. It is not a whole-session receipt. Save outputs outside the selected tree, and compare repeated runs with identical inputs. See [measurement evidence](BENCHMARK-20261030.md) and [CI/cache guidance](MODALITIES.md#ci--prompt-cache-prefix-stability). ## Responsibilities This table uses the scope contract's wording, with unshipped provisions marked `(planned)`. Prebuilt archives with `SHA256SUMS`, cosign signatures, SBOM and provenance are available; see [download verification](VERIFYING.md). | Level | dctx provides | You are responsible for | |---|---|---| | System binary | Release archives with cosign signatures, SBOM and provenance, cache caps, `dctx doctor`, journals (planned), receipts (planned) | Choosing roots, policy file, keeping one version on PATH | | Project library | Pinned vendored binary and protocol client (Node on npm; Python and Go from CI), same bytes as CLI (checked in CI) | Pinning the version, exclusions in the project policy, not re-implementing engine logic | | Agent shell setup | CLI commands and `agent-setup` guidance | Choosing roots, bounding answers and measuring whole sessions | | CI and cache | Byte-stable pack, prefix tiers (planned), deterministic exit codes | Pinning the binary, caching the index between runs, treating pack drift as a signal not noise | For current CLI exclusions, use `.gitignore` and `.dctxignore`; the unified policy file is planned. Agent session ids and general receipts in the responsibility column describe planned integrations. The Rust facade exists today with explicit host-supplied selection and storage policy; the project-library row describes the Python, Node and Go wrappers, with Node available on npm. Existing pack prefix stability is distinct from the planned layered prefix tiers. ## Two scopes, one binary The following is the distribution contract for the project-library wrappers and signed releases: > The system `dctx` on PATH belongs to you and your agents. A binary installed by a project library lives inside that project (virtualenv, node_modules), pinned and managed by that package manager. Same signed engine, different owner. Interactive agents call the system binary; application code and CI call the project binary; a library never silently falls back to PATH. Today, install the system binary from release archives. The Python, Node and Go wrappers already follow the no-fallback contract: they resolve an explicit path, `DCTX_BIN`, their own platform package (Python, Node) or a versioned user cache, and never search `PATH`. Until they are published, install them from CI artifacts or a checkout, or invoke an explicitly pinned CLI path. The Rust facade is an in-process library, not a vendored executable. The CLI cache lives in `<cache-parent>/<engine-major.minor>/` under the platform-specific `dctx/v2` parent (or `DCTX_CACHE_DIR`), so engines 1.2 and 1.3 keep separate indexes while patch releases of one family share theirs (see [scopes](SCOPES.md)). A version/path line in every pack is planned. Today `dctx rpc` reports the engine version in `hello`, and `dctx doctor` lists the dctx binaries visible from a directory. Check the executable path and version explicitly, and use separate absolute `DCTX_CACHE_DIR` locations when two installations of the same engine family must not share an index. Both future scopes should read the project's exclusions; today the CLI loads ignore files while a Rust host supplies its own selection rules. Continue with the [documentation index](README.md), [modalities](MODALITIES.md) or [engine specification](SPEC.md). </FILE_CONTENT_END ID="F021"> <FILE_CONTENT_START ID="F022" PATH="docs/WHY-DCTX.md" LINES="160"> <!-- SPDX-License-Identifier: Apache-2.0 --> <!-- SPDX-FileCopyrightText: 2026 Eris Margeta --> # Why dctx exists What problem dctx solves, the rules it follows, and why "byte-identical output" matters even if you never think about bytes. ## The problem An AI coding assistant only knows what is in its **context window**: the text sent to the model with your request. It cannot see the rest of your project. Most projects are too large to send whole, so tools pick pieces. Often they pick badly: whole files when one function would do, text that looks similar but is the wrong code, code as it was before your last edit, or half a function. Each of these costs you. Models read text as **tokens** (small chunks of text, roughly a short word or part of one), and providers bill per token. The model reads every token before it answers, so more tokens also means more waiting. And answers get worse as irrelevant text piles up. The [README](../README.md#the-core-belief-prompt-processing-efficiency) sums it up: every token in front of a model is paid for three times, to read it, again when a cache is missed, and again in attention. ## What dctx does dctx is a command-line tool that reads your project on your machine and answers precise questions about it: where a function is defined, what calls it, what its exact source is. Each answer fits a size budget and is built from whole pieces of syntax; a piece that is too long is marked as cut, with a way to get the rest. The same question about the same code gives the same bytes every time. An assistant can run the commands through its shell tool. dctx can also pack a whole project into one structured block for a chat. ### Start with grep plus file reads The baseline is a literal search followed by reading the relevant files or line ranges. That is often enough for a short task. dctx earns its place when exact symbol reads and outlines avoid repeatedly sending large, irrelevant files. It aims to be one context-management tool across these workflows; choose the surface that fits in [Choosing how to use dctx](MODALITIES.md). ### A small worked example Run with dctx 1.1.0 on a copy of this repository's `crates/dctx-lex-go` folder. The output is real and complete. ```text $ dctx map find Add # dctx-lex-go find s:tests/fixtures/basic.go#Add fn L43-45 $ dctx map read 's:tests/fixtures/basic.go#Add' # dctx-lex-go read s:tests/fixtures/basic.go#Add fn tests/fixtures/basic.go func Add[T ~int](a, b T) T { return a } $ dctx map neighbors 's:tests/fixtures/basic.go#Add' --edge calls --dir in # dctx-lex-go neighbors calls:in:s:tests/fixtures/basic.go#main fn tests/fixtures/basic.go L59 ``` `find` returns a stable id, the kind of thing it is (a function) and its lines. This is a historical 1.1.0 transcript; the current CLI also includes verified source bytes in text `read` output, or in `source_utf8` with `read --json`. `neighbors` says that `main` calls it, on line 59. ## The philosophy The [specification](SPEC.md#2-the-core-belief-prompt-processing-efficiency) turns this into five testable rules. **Bounded.** Every map answer has a size ceiling, reserved before anything is written, and a record is never split. The budget is up to 2,000 estimated tokens (1,000 for `explain`). *Why it matters to you:* one question cannot flood the context window and crowd out your own instructions. **Deterministic.** The same code and the same question give the same bytes. *Why it matters to you:* results are repeatable, and repeated prompts can be served from a cache. **Prefix-stable.** When context is sent again across turns, bytes that did not need to change do not change. *Why it matters to you:* this is what keeps caching working across a conversation. **Non-redundant.** Within one session, do not resend what was already sent unless it changed. This one is still a target. **Honest.** Every answer states its freshness, precision and provenance, and dctx never asserts what it does not know. With `--json`, the `read` above carries `"freshness":{"mode":"strict","state":"verified"}`, a `precision` block, and `more` and `next` fields for anything that did not fit. Calls it cannot resolve are listed as `unresolved`, not guessed. *Why it matters to you:* you and your assistant can tell a fact from a guess. The docs add a few more commitments: - **Offline.** No telemetry, no update checks, no model calls. A release check counted zero network connections across 16 commands. Nothing leaves your machine. - **Private by default.** A file is classified before any byte of it is read. Secret-shaped files such as `.env`, `*.pem` and `id_rsa` are listed with content omitted, with no override in v1. - **No embeddings.** dctx does not turn code into vectors and search by similarity. It ranks by names and syntax. - **Features must earn their place.** A feature without a measured acceptance gate is not a dctx feature. ## Why byte-identical output matters ### Prompt caching, in plain words Much of each request to an AI model repeats the last one: system instructions, project context, earlier turns. Providers keep a cache of prompt beginnings. If the **start** of a new prompt matches a cached one exactly, byte for byte, they reuse their earlier work on that part. Cached input costs a fraction of the normal price and is processed faster. The match must be exact, and it is checked from the beginning. Picture a reader who remembers the first fifty pages you sent earlier. Send the same fifty pages and they skip ahead. Change one word on page two, and from that word on they must read everything again, even if pages three to fifty are unchanged. So one changed byte early in a prompt (a timestamp, a file listed in a different order, a file size) breaks the cache for everything after it. ### Prefix-stable, simply "Prefix" means the beginning of a text. "Prefix-stable" means the beginning stays the same unless the content there really changed. Edit one file, and only the bytes from that file onward should differ. Timestamps are the classic problem. In 1.0.0, every line of the `dctx pack` file tree carried a modification time, and file lines a size. The tree sits near the top, so merely re-saving a file (a `touch`) changed almost the whole page as far as a cache is concerned. Since 1.1.0 tree lines carry only an id. A bare `touch` leaves the output byte-identical, and an edit keeps everything before the edited file as a shared prefix. `--tree-stamps=on` brings back the old lines. In the same folder we appended one comment line to the last file in the tree, `tests/review_lexers_a.rs`, and compared `dctx pack .` before and after: ```text default output: first 117,215 of 122,437 bytes unchanged --tree-stamps=on: first 2,151 of 123,159 bytes unchanged ``` By default about 96% of the page is still a reusable prefix. With timestamps on, almost nothing is. ### The evidence The [stability report](research/stability-20261105/REPORT.md) measured map answers on 6 November 2026, on three pinned local corpora with 11 kinds of question each. **33 of 33** text answers and **33 of 33** JSON answers were byte-identical after an unrelated edit elsewhere in the project, and all were identical over five separate runs. The report states its limits too. It measures dctx's answers, not a provider's cache hits. It ran on Linux only. The layered design that would keep context prefix-stable across a whole conversation ([SPEC §12.1](SPEC.md#121-prefix-stable-tiers-target)) is still a target. ### Savings belong to the system dctx on its own does not save tokens by default. In the [11 November benchmark](BENCHMARK-20261111.md), the dctx CLI arm used 5.01 % fewer median total tokens than grep plus file reads, far below the 25 % rule. Token savings come from systems that use dctx: a harness or agent system built around its cache-hit philosophy, reusing byte-identical, prefix-stable context across long sessions over a large body of work. In that system, dctx behaves like any sufficiently advanced caching mechanism, with one difference: you have complete control over every byte of the context. The system must keep and reuse that context to benefit. There is no measured, citable savings figure for such a system yet. ### An illustration of money and time *Made-up numbers, not any provider's prices.* Assume: - an agent sends the same 20,000 tokens of project context on each of 10 turns; - normal input costs 10 units per 1,000 tokens, cached input 1 unit; - the cache holds between turns. If the context is byte-identical, turn one pays 200 units and the next nine pay 20 each: 380 units. If a timestamp near the top changes every turn, every turn pays 200: 2,000 units. The model also re-reads all 20,000 tokens every turn instead of reusing them, so each answer takes longer. The saving in this illustration belongs to the agent system that keeps the context stable and reuses it through the provider cache. dctx supplies controllable bytes; it does not produce that saving on its own. Real ratios differ by provider; the mechanism is the same. ### Other reasons determinism matters - **Reproducible reviews.** A colleague who runs the same command on the same code sees exactly what the assistant saw. - **Meaningful diffs.** If saved context changes, the code changed, not a clock or a sort order. - **Trust.** A tool whose answers shift for no reason is hard to rely on. In the spec's words, "trust is the product". ## What dctx is not - **Not a type checker.** Call edges come from names, scopes and imports; ambiguous references are dropped. - **Not exact token counting.** Budgets use an estimate, `ceil(2 × UTF-8 bytes / 7)`, not a model's tokenizer. - **Not vector search or RAG.** No embeddings in the core, and the engine never calls a model. - **Not a hosted service or a daemon.** One binary that runs when you call it. No telemetry, not even opt-out. - **Limits still matter.** Plain `dctx pack` sends the selected project without an output budget by default. A 100 GB tree needs scoping, and the cache has a 2 GiB hard cap. CI covers Linux, macOS and Windows; byte-stability measurements here ran on Linux only. ## Where to go next - [README](../README.md): install, quick start, map mode. - [Specification](SPEC.md): rules, metrics, roadmap. - [Measurement evidence](BENCHMARK-20261030.md): grep plus file reads first; other-tool numbers are secondary historical notes. - [Stability report](research/stability-20261105/REPORT.md): protocol, raw answers and limits. - [Map mode guide](guides/MAP-MODE.md): every verb and option. ## Sources in this repository - [README.md](../README.md): core belief, map-mode budgets, `pack` tree lines, `--tree-stamps`, tested platform. - [CHANGELOG.md](../CHANGELOG.md): 1.1.0 prefix-stable `pack` output, stability re-measurement. - [docs/SPEC.md](SPEC.md): §2 rules PPE-1 to PPE-5, §3 defects R1 and R7, §4 privacy and no network, §11 page formats, §12.1 tiers, §13 token estimate, §32 non-goals. - [docs/research/stability-20261105/REPORT.md](research/stability-20261105/REPORT.md): 33/33 results and limits. - [docs/BENCHMARK-20261030.md](BENCHMARK-20261030.md): `unresolved` call records. - Worked example and prefix figures: output of dctx 1.1.0 (`a4f6378`, built from [crates/dctx-cli](../crates/dctx-cli)) on a copy of [crates/dctx-lex-go](../crates/dctx-lex-go). </FILE_CONTENT_END ID="F022"> <FILE_CONTENT_START ID="F025" PATH="docs/design/contracts/DTS-v2.md" LINES="92"> <!-- SPDX-License-Identifier: Apache-2.0 --> <!-- SPDX-FileCopyrightText: 2026 Eris Margeta --> # DTS source v2 and compiled plan IR v1 Status: current versioned design sketch; proposed syntax is not a release promise. Defines organization control of every mode under the accepted structure. Depends on API, identity and parser contracts; shared by the facade and mode engines. Preserves the v1 compiler/rendering contract while extending typed policy. ## Compatibility and typed plan DTS v1 variables, partials, layouts, four marker definitions, static resolution and runtime data injection remain valid with byte-identical fixture outputs. A version declaration selects v2; never infer version by an unknown field. Legacy defaults compile to an explicit pack plan. Every map/future mode request also receives a compiled default/custom plan; there is no second hidden policy language or engine path bypassing DTS. ```text ContextPlanV1 = { source_language_version, ir_major:1, ir_minor:0, required_capabilities, selection_rules, extraction_rules, budget_rules, views, render_program, selection_digest, extraction_digest, render_digest, plan_digest } ``` | Typed section | Responsibility | Validation | |---|---|---| | SELECT | Paths/languages/kinds and Include/Exclude/OmitContent/DebugVisible policy | Root-relative paths, bounded rule count, no grant expansion | | INDEX | Requested facts, parser/dialect, extraction limits | Available parser capability; Rust default `syn`; optional native only explicit | | BUDGET | Final bytes/estimated tokens, records/depth, parse/memory/work bounds | Nonnegative bounded quantities; intersect host/mode ceilings; overflow refused | | VIEW | Pack/map/future projection naming selection/extraction/budget/render refs | All references resolved, acyclic, mode capability present | | RENDER | Existing partials/layout/markers plus bounded record iteration | No arbitrary evaluation, filesystem/network/process access or loaded plugins | Source examples in proposal §2 are illustrative; B2 freezes precise grammar and source fixtures before parser implementation. The typed semantics above are normative. Custom source is built with explicit `template build`; shipped compiled defaults need no runtime source parse. Template *sources* remain user-owned; compiled plans are reconstructible cache entries. ## Permission and budgets `permission = host_grant ∩ organization_ceiling ∩ session_selection`. Within that ceiling, preserve existing ordered last-match ignore/omit semantics. A template can narrow access but never turn a host denial into Include. DebugVisible authorizes metadata only. Read rule/config sources through explicit capabilities; unreadable policy is `PolicyUnavailable`, never default-allow. Compiled plans bind their policy inputs/revision; changed/removed policy sources invalidate authorization before cached facts or render output can be served. Selection/extraction digests change index validity independently. Rendering-only changes do not reparse source; they still change the plan/render digest and continuation compatibility. A parser capability/revision change alters FactKey. Budget/depth narrowing cannot make previously unauthorized facts visible. Final-output token estimate is `ceil(2 * UTF8_bytes / 7)` over the complete encoded answer. Rendering reserves headers, delimiters, escaping and continuation before choosing whole records. Loops traverse only authorized records under iteration/work bounds. Cyclic partials, unknown variables/opcodes, missing capabilities and impossible envelopes are typed errors; no fallback rendering that violates the configured mode or privacy ceiling. ## Compiled IR envelope IR magic `DCTXIR\0\0` (8 bytes), major/minor u16, exact total length u64, required capability bitset u64, section_count u32, followed by bounded typed sections. Each section has `kind:u16, schema:u16, length:u32, payload[length]`. Trailing SHA-256 covers all preceding bytes. Integer encoding is little-endian; strings have checked u32 byte lengths and UTF-8. Maximum plan 1 MiB, 64 sections, 10,000 instructions; caller may narrow. Unknown required section/opcode/version refuses load. No native-memory layout or executable serialized pointers. Canonical sections order SELECT/INDEX/BUDGET/VIEW/RENDER/provenance, sorted named definitions with source rule order preserved inside each. Domain-separated identity framing (identity v1 kind 8) defines plan_digest; render_digest uses kind 8 with a distinct IR schema/domain payload identifying render-only input. Selection uses kind 4, extraction kind 5. B2 supplies canonical encoding goldens and corruption fuzzing before compiled IR is a release format. ## Owner tests and model B2 owns v1 parity, v2 compile/load determinism, section/opcode rejection and positive controls; P1 authorization-before-render, P5 final budget, P6 frozen clock/reordered-input equality. Model compile->validated-plan->authorized-view-> bounded-render transitions and policy-epoch revocation. Mutation removing the host intersection must fail a denied-content test. Mutation budgeting unescaped strings must fail a Unicode/JSON envelope property. Unsupported parser tests include a positive `syn` capability case and explicit optional tree-sitter case. Future modes must add their typed VIEW capability and conformance fixture to this same compiler/facade contract before release. </FILE_CONTENT_END ID="F025"> <FILE_CONTENT_START ID="F027" PATH="docs/guides/AGENTS-SNIPPET.md" LINES="25"> <!-- SPDX-License-Identifier: Apache-2.0 --> <!-- SPDX-FileCopyrightText: 2026 Eris Margeta --> # AGENTS.md snippet: task context from dctx Paste the section below into a project's `AGENTS.md` (or `CLAUDE.md`) so coding agents start from dctx context. ## Notes for coding agents Before editing, pull the code your task names, cut to a budget: ```sh dctx pack --for "$TASK" --budget 3000 ``` `$TASK` is the task description. dctx runs `map find` on the names the text mentions (backticked words, snake_case, camelCase, `a::b`, then longer plain words), then `map neighbors` and `map read` on the best hits, and prints whole lines until the budget is spent. The budget is in estimated tokens, ceil(2 × UTF-8 bytes / 7), not a tokenizer count. The last line reports the estimate and how many lines were dropped. Exit 1 means no name in the text matched the index. Name things in the text: `--for main` or `--for Session` works, but a sentence such as "how does caching work" only matches loose words, and dctx says so on stderr (the page itself is unchanged). Put a short name next to prose in backticks, as in ``--for 'fix `run` in the pack command'``. Then narrow with `dctx map find`, `dctx map neighbors <id>` and `dctx map read <id>` as needed (`dctx map --help`). </FILE_CONTENT_END ID="F027"> <FILE_CONTENT_START ID="F028" PATH="docs/guides/MAP-MODE.md" LINES="375"> <!-- SPDX-License-Identifier: Apache-2.0 --> <!-- SPDX-FileCopyrightText: 2026 Eris Margeta --> # Map mode Map mode explores a project through bounded outlines, symbol searches and source reads. It builds the index automatically; there is no user `index` command. The current CLI uses the shared dctx facade. Older storage and Git-based designs in [SPEC-MAP-MODE](../SPEC-MAP-MODE.md) are not the current CLI contract. dctx and this guide are Apache-2.0. For an agent using a shell, see the [agent snippet](AGENTS-SNIPPET.md). ## Definitions outside the index For `find`, `neighbors`, `explain`, `read`, `grep`, `trace`, `impact` and `context`, a literal local import can explain a missing definition. When an eligible referenced file defines the requested or imported name, the page includes: ```text defined outside index: ../lib/shared.py add it with --also ../lib ``` JSON adds `defined_outside_index`, an array of objects with `path` and `hint`. The notice does not turn a missing result into a successful indexed result. The fallback checks literal relative imports/includes, Rust path attributes and path dependencies, plus sibling Python `from` and Rust `use` targets. It searches only below the indexed directory's parent; it does not consult package managers, environment search paths or arbitrary sibling files. It uses the same ignore, omit and sensitive-file policy and refuses symlink components. Its limits are 256 file attempts, 2 MiB of source bytes, 64 KiB per file, 2048 directory entries, 16 directory levels and 100 ms. Results are sorted by displayed path. A bounded scan can miss definitions; this is a hint rather than semantic resolution. Add roots explicitly to query their definitions and source together: ```sh dctx map find shared --place app --also lib dctx map read 's:lib/shared.py#shared' --place app --also lib dctx context shared --place app --also lib dctx pack app --also lib --for 'shared' ``` `--also DIR` is repeatable on every map verb, `pack` and `context`. Directories are relative to the invocation directory. With extra roots, all paths and IDs carry their root directory label, for example `s:app/main.py#run` and `s:lib/shared.py#shared`. Root labels must be distinct. Each root keeps its own selection rules and is read-only. The canonical, sorted root set keys the cache; changing the order of `--also` does not change identities or reuse another set's index. Without extra roots, existing IDs stay unchanged. ## Commands ```text dctx map <map|find|neighbors|explain|read|skeleton|grep> <TARGET> [OPTIONS] dctx map hubs [--limit N] [--json] [--place PATH] [--budget TOKENS] [--meta] dctx map path <FROM> <TO> [--json] [--place PATH] [--budget TOKENS] [--meta] dctx trace <A> <B> [--max-depth N] [--max-paths N] [--max-bytes N] [--json] dctx impact <SYMBOL> [--max-depth N] [--max-sites N] [--max-bytes N] [--json] dctx map export [--format json|mermaid] [--output PATH] [--place PATH] ``` | Verb | Use | | --- | --- | | `map TARGET` | Outline a place-relative file or a node; TARGET is required (omitting it does not scan). | | `find TARGET` | Search for a name or concept; quote multiword targets. | | `neighbors TARGET` | Inspect a node's relations. | | `explain TARGET` | Inspect one node's details. | | `read TARGET` | Read a node's verified source; a long node pages with `--cursor`. `dctx read` is the same verb. | | `skeleton FILE` | A file's (or `m:<path>`'s) declaration signatures in source order, no bodies. | | `grep LITERAL` | Exhaustive literal search of indexed files, hits grouped by enclosing symbol. | | `hubs` | Most-called symbols and per-directory file and symbol counts. No TARGET. | | `path FROM TO` | Shortest edge path (calls, imports, contains; either direction; at most 8 hops), or `no path`. | | `trace A B` | Shortest directed call/reference paths between two symbols in one bounded answer. | | `impact SYMBOL` | Direct reference/call sites and transitive callers, grouped by file with counts. | | `export` | The whole graph as one deterministic JSON or Mermaid document; no token cap. | Copy node IDs from results: `m:sample.py` names a module and `s:sample.py#PythonBeacon` names a symbol. `dctx map <verb> --help` prints each verb's own page and example. The following option descriptions follow `dctx map --help` ([source](../../crates/dctx-cli/src/map/args.rs)): | Option | Meaning / bounds | | --- | --- | | `--json` | Facade JSON v2, including the precision label. | | `--place PATH` | Place or worktree root; default: current directory. | | `--meta` | Restore the snapshot digest and generation in the text header and JSON. Without it, answer bytes do not change across unrelated edits or time. | | `--profile` | Stage timings and the five slowest files on stderr (`DCTX_PROFILE=1` is the same switch). | | `--budget TOKENS` | Output tokens, 1..2000; `explain` max: 1000. `read` with no `--budget` uses the 2,000-token hard cap. | | `--depth N` | `map`: 1..3; `neighbors`: 1..4. `explain` and `read` take no depth. | | `--limit N` | `map`, `find`, `neighbors` page size; `explain` and `read` accept only 1. `hubs`: 1..60 lines, default 20. | | `--offset N` | Refused. Pass the previous page's `next` value to `--cursor`. | | `--cursor TOKEN` | Opaque continuation. A stale token is rejected. | | `--kind fn,type,doc` | `find`: comma-separated node kinds. | | `--in PATH` | `find` or `grep`: restrict to a relative path. | | `-i`, `--ignore-case` | `grep`: ASCII case-insensitive match. | | `--edge calls,imports` | `neighbors`: comma-separated edge filter. | | `--dir in\|out\|both` | `neighbors`: relation direction. | | `--lines A-B --full` | `read`: exactly those absolute source lines inside the node; `--full` permits 400. | | `--rev SHA` | Refused: this build does not link Git. | Environment bounds: `DCTX_MAX_SOURCE_BYTES` (total source bytes one scan may read, default 1 GiB), `DCTX_MAX_RECORDS` (files, symbols and edges one index may hold, default 1000000), `DCTX_MAX_ENTRIES` (files and directories one scan may visit, default 100000) and `DCTX_FRESHNESS` (see below). The parser also accepts these `--kind` values: `method`, `struct`, `enum`, `trait`, `impl`, `const`, `macro`, `class`, `interface`, `symbol`, `module`, `package`, `place`, `test`. Edge names also include `contains`, `implements`, `uses-type`, `tests`, `documents`, `reexports`. The token estimate is `ceil(2 * UTF-8 bytes / 7)`, not a tokenizer guarantee. ## Trace: how A reaches B ```sh dctx trace main dispatch --max-depth 8 --max-paths 10 dctx trace 's:src/main.rs#main' 's:src/router.rs#dispatch' --json ``` `trace` follows directed call and import/reference edges in the indexed graph. It returns the shortest paths, ordered by each hop's file, declaration line and stable ID. Container edges do not create shortcuts. Every text line is one complete path: ```text chain.py:1 start -> chain.py:4 middle -> chain.py:7 branch -> chain.py:10 leaf ``` Names must match one indexed symbol exactly; use stable IDs when a name is ambiguous. Missing endpoints and disconnected symbols return `no path within bounds`. A depth cutoff, excess shortest paths or a byte cutoff adds a `truncated:` line. A path is retained whole or dropped whole. | Option | Default | Allowed range | | --- | --- | --- | | `--max-depth N` (`--depth N`) | 8 | 1..=16 hops | | `--max-paths N` | 10 | 1..=100 shortest paths | | `--max-bytes N` | 65536 | 256..=1048576 UTF-8 bytes | `--json` emits an object with `v: 2`, `verb: "trace"`, `paths` (arrays of locations), `counts.paths`, `bounds` and `truncated`. A location contains `id`, `file`, `line`, `symbol` and `depth` (zero for trace hops). Counts describe the returned paths. An empty result has `paths: []`. ## Impact: what depends on a symbol ```sh dctx impact dispatch --max-depth 4 dctx impact 's:src/router.rs#dispatch' --max-sites 1000 --json ``` `impact` lists direct identifier references and call lines, then distinct transitive callers through the same directed graph. Each direct line carries its innermost enclosing symbol. References are scanned from verified indexed source, with comments and string literals masked and declaration names skipped; import aliases are included. Indexed references are still returned when the definition is outside the index, alongside the eligible outside-index notice. Like the existing graph, these are conservative structural matches, without semantic name or type resolution. Repeated uses on one source line in one enclosing symbol count as one site. Output is grouped by file in lexical order, with direct sites in source order and transitive callers in declaration order. Each group and the page report returned direct-site and transitive-caller counts. Callers have their shortest caller depth; cycles do not repeat a caller. A `truncated:` line reports a depth, record or byte cutoff. Direct sites take priority when the record or byte cap requires a smaller answer. | Option | Default | Allowed range | | --- | --- | --- | | `--max-depth N` (`--depth N`) | 8 | 1..=16 caller hops | | `--max-sites N` | 1000 | 1..=10000 combined direct sites and transitive callers | | `--max-bytes N` | 65536 | 256..=1048576 UTF-8 bytes | `--json` emits `v: 2`, `verb: "impact"`, `files`, `counts`, `bounds` and `truncated`. Each file group contains `file`, `direct`, `callers` and `counts`; locations use the same fields as trace, with direct `depth: 1` and transitive `depth >= 2`. Page counts contain `files`, `direct_sites` and `transitive_callers`; group counts contain the latter two. Empty results have `files: []` and zero counts. Both verbs also accept `dctx map trace` / `dctx map impact`, `--place PATH` and repeatable `--also DIR`. They share the deny list, root labels, cache identity, and outside-index notice resolution described above. Notices count towards the byte cap; a cap too small for mandatory metadata and notices is refused. Neither verb uses `--budget` or cursors. Bounds errors name the verb, option, value and allowed range and exit 2. Index/source scan ceilings still apply. Engine RPC advertises `trace` and `impact` and returns their exact JSON pages. ## Languages and precision This table is the output of `dctx languages --markdown` for the release build (`dctx languages --json` gives the same data as JSON). Extension matching is case-insensitive: `Upper.RS` is indexed as Rust. | Language | Tag | Files | Tier | Confidence | |---|---|---|---|---| | Rust | `rust` | `.rs` | full | structural | | JavaScript | `javascript` | `.js`, `.mjs`, `.cjs`, `.jsx` | full | structural | | TypeScript/TSX | `typescript` | `.ts`, `.mts`, `.cts`, `.tsx` | full | structural | | Python | `python` | `.py`, `.pyi` | full | structural | | Go | `go` | `.go` | full | structural | | Java | `java` | `.java` | full | structural | | C/C++ | `c` | `.c`, `.h`, `.cc`, `.cpp`, `.cxx`, `.hpp`, `.hh` | full | structural | | C# | `csharp` | `.cs` | full | structural | | Kotlin | `kotlin` | `.kt`, `.kts` | full | structural | | Ruby | `ruby` | `.rb`, `.rake`, `.gemspec`, `Rakefile`, `Gemfile` | full | structural | | PHP | `php` | `.php`, `.phtml`, `.inc` | full | structural | | Swift | `swift` | `.swift` | full | structural | | Vue/Svelte/Astro/HTML script blocks | `web` | `.vue`, `.svelte`, `.astro`, `.html`, `.htm` | full | structural | | Scala | `scala` | `.scala`, `.sc` | full | guess | | Dart | `dart` | `.dart` | full | guess | | Zig | `zig` | `.zig` | full | guess | | Solidity | `solidity` | `.sol` | full | guess | | Gleam | `gleam` | `.gleam` | full | guess | | Fortran | `fortran` | `.f90`, `.f95`, `.f03`, `.f08`, `.f`, `.for` | full | guess | | Perl | `perl` | `.pl`, `.pm`, `.t`, `.psgi` | full | guess | | Groovy | `groovy` | `.groovy`, `.gradle` | full | guess | | PowerShell | `powershell` | `.ps1`, `.psm1`, `.psd1` | full | guess | | Elixir | `elixir` | `.ex`, `.exs` | full | guess | | Lua | `lua` | `.lua` | full | guess | | OCaml | `ocaml` | `.ml`, `.mli` | full | guess | | R | `r` | `.r` | full | guess | | Julia | `julia` | `.jl` | full | guess | | Haskell | `haskell` | `.hs` | full | guess | | Erlang | `erlang` | `.erl`, `.hrl` | full | guess | | Verilog/SystemVerilog | `verilog` | `.v`, `.vh`, `.sv`, `.svh` | full | guess | | Terraform/HCL | `hcl` | `.tf`, `.tfvars`, `.hcl` | full | guess | | SQL | `sql` | `.sql`, `*.sql.in` | full | guess | | Clojure | `clojure` | `.clj`, `.cljs`, `.cljc`, `.edn` | full | guess | | Common Lisp | `lisp` | `.lisp`, `.lsp`, `.cl` | full | guess | | Scheme | `scheme` | `.scm`, `.ss` | full | guess | | Emacs Lisp | `elisp` | `.el` | full | guess | | JSON/JSONC/TOML/YAML | `config` | `.json`, `.jsonc`, `.toml`, `.yaml`, `.yml` | outline | structural | | Shell | `shell` | `.sh`, `.bash`, `.zsh`, `.bats` | outline | guess | | Makefile | `make` | `.mk`, `Makefile`, `GNUmakefile` | outline | guess | | Dockerfile | `docker` | `Dockerfile`, `Containerfile` | outline | guess | | Protobuf | `proto` | `.proto` | outline | guess | | Pascal | `pascal` | `.pas`, `.pp`, `.dpr` | outline | guess | | GraphQL | `graphql` | `.graphql`, `.gql` | outline | guess | | Nix | `nix` | `.nix` | outline | guess | | Markdown | `markdown` | `.md`, `.markdown` | docs | structural | | Plain text | `text` | `.txt` | docs | structural | | reStructuredText | `rst` | `.rst` | docs | structural | | AsciiDoc | `asciidoc` | `.adoc`, `.asciidoc` | docs | structural | | Org | `org` | `.org` | docs | structural | | LaTeX | `tex` | `.tex` | docs | structural | Tiers: **full** extracts symbols and call edges, **outline** symbols only, and **docs** headed sections. Confidence `guess` marks heuristic outlines, whose records carry confidence `guess`. See [language coverage](../LANGUAGE-COVERAGE.md). Rust uses `syn` in release builds (the `syntax-rust` feature, reported as parser `dctx-lex-rust/syn-<version>` with `syntax` coverage), for supported Rust syntax only and without type checking. The other languages use the first-party structural lexers, including the JS lexer for TypeScript/TSX and the heading extractors for documents. This is not a promise of exact semantic calls, type resolution or macro expansion. `dctx --version --verbose` lists the parsers and features of the running build. JSON answers expose `precision.coverage`, `precision.completion` and `precision.parser` (the default structural parser identity is `dctx-structural/3`). The [model](../../crates/dctx-map-model/src/domain/precision.rs) distinguishes `structural`, `syntax` and `opaque` coverage from `complete`, `partial` and `refused` completion. These labels describe extraction, separately from edge confidence. Unsupported extensions provide no extracted symbols; the smoke test checks empty records for `OpaqueBeacon` in `sample.unknown`. ## Index, cache and privacy Each invocation opens a facade session and can reuse a compatible persisted map generation after checking its inventory and file freshness. The default stamp mode trusts settled files with unchanged size, mtime and inode; `DCTX_FRESHNESS=strict_live` hashes every file on a warm start. Exact source reads still verify live bytes. There is no persistent CLI graph database. The retired per-worktree SQLite cache selector (`map/storage.rs`) has been deleted; the CLI does not read `DCTX_MAP_CACHE`. The shared cache stores `ledger.v1`, `policy.v1`, serialized generations and view manifests in managed object files. Generations contain file inventory, digests and stamps, nodes, signatures, summaries, spans and edges, rather than copies of all source contents. See [Choosing how to use dctx](../MODALITIES.md#huge-trees-scope-before-indexing) for huge-tree scoping and the behavior when the cache cap is reached. Set `DCTX_CACHE_DIR` to an absolute path to override its root. Otherwise it is: | Platform | Cache root | | --- | --- | | macOS | `~/Library/Caches/dctx/v2` | | Windows | `%LOCALAPPDATA%/dctx/Cache/v2` | | Other | `$XDG_CACHE_HOME/dctx/v2`, or `~/.cache/dctx/v2` | The implemented lifecycle follows [DX-ARCH-08](../archive/design/ARCHITECTURE-DECISIONS.md): time-based expiry, a system size cap and an automatic cleaner. Defaults are 7 days for idle overlays/previews, 30 days for unpinned roots and 1 day for staging; the hard cap is 2 GiB, the soft watermark 1.5 GiB and the eviction target 1.2 GiB. These are cache policies, not a claim that every map query persists those object types. ```sh dctx cache status --json dctx cache gc --dry-run dctx cache purge --root /absolute/project/path --dry-run dctx cache purge --all --dry-run dctx cache config auto off --max-bytes 1000000 --ttl-days 7 dctx cache auto ``` `status` accepts `--root PATH`; `gc` accepts `--root PATH`, `--max-bytes N` and `--legacy`. Applying `purge` requires `--yes` and either `--root PATH` or `--all`. `cache config` without arguments shows persisted policy; `auto on|off` controls auto-clean, and `--max-bytes` can only tighten the cap. Pack, map, template, plugin and TUI commands run one bounded cleanup when due (daily by default). `--no-auto-clean` or `DCTX_AUTO_CLEAN=0` disables that slice. Ignored files are excluded before content reads; omitted files may have metadata listed but their content is never read. The host loads the global ignore file (`<config dir>/dctx/ignore`: `$XDG_CONFIG_HOME/dctx/ignore` or `~/.config/dctx/ignore` on Linux and macOS, `%APPDATA%\dctx\ignore` on Windows), root and nested `.gitignore` rules, then the chosen root's `.dctxignore`. `DCTX_INDEX_IGNORED=1` skips those ignore texts; built-in sensitive-file and `.git` exclusions still apply. The core does not read Git metadata or run Git, so `.git/info/exclude` and Git's `core.excludesFile` are not applied. The optional Git plugin has separately disclosed authority; see [Plugins](PLUGINS.md). ## Two worked examples These fixtures and output fragments are copied from [`map_cli.rs`](../../crates/dctx-cli/tests/map_cli.rs). The test checks fragments, not full transcripts; the output blocks below are excerpts, without invented columns or counts. Create a project containing `sample.py`: ```python def PythonBeacon(): return 1 ``` From that project, outline its module: ```sh dctx map map m:sample.py --depth 2 --budget 2000 ``` Expected output contains: ```text s:sample.py#PythonBeacon ``` For the second example, add `sample.unknown` with: ```python def OpaqueBeacon(): return 1 ``` Search the unsupported source extension: ```sh dctx map find OpaqueBeacon --json ``` Expected JSON contains this exact fragment and does not contain `OpaqueBeacon`: ```text "records":[] ``` For crate responsibilities and optional parser dependencies, see the [crate map](../CRATE-MAP.md). </FILE_CONTENT_END ID="F028"> <FILE_CONTENT_START ID="F029" PATH="docs/guides/PLUGINS.md" LINES="162"> <!-- SPDX-License-Identifier: Apache-2.0 --> <!-- SPDX-FileCopyrightText: 2026 Eris Margeta --> # Plugins A plugin adds commands or hooks through a bounded, versioned JSON protocol over stdio. The host brokers its requested effects; installation, enablement, capability consent and execution admission are separate steps. Bundled code can run as a worker of the same executable; independently installed artifacts use the plugin protocol. Availability is limited as described below. dctx, the bundled Git plugin and this guide are Apache-2.0. ## Bundled Git plugin and consent The default CLI includes `dctx/git` version `1.0.0`, with alias `dctx git` and the verbs `status` and `protect`. The catalog defaults to enabled. A fresh CLI without a consent record reports `enabled` with `needs-consent`; shipping the worker does not grant its capabilities or guarantee that it can launch. `dctx git` is a plugin alias, not a general Git passthrough. The [bundled manifest capabilities](../../crates/dctx-cli/src/plugin/bundled.rs) disclose these grants: | Capability | Bound | | --- | --- | | Required `file.read` | Project `.gitignore`, at most 1,048,576 bytes. | | Required `file.write` | Existing project `.gitignore` only (`create=false`); growth at most 4,096 bytes, total at most 1,052,672 bytes. | | Optional `program.run` | Program `git`, operation `git.add-ignore`, resource `git-admin:stage-ignore`, output at most 65,536 bytes. | | Outputs / network | Neither requested. | This narrow optional Git recipe belongs to the plugin boundary. The map/core does not run Git, read `.git/` or use Git hashes for identity. Review the requested capabilities before approving: ```sh dctx plugin list dctx plugin info dctx/git --json dctx plugin enable dctx/git --approve dctx plugin disable dctx/git ``` `--approve` records consent for the displayed capability set. New installations remain inactive until enabled; combined `install --enable` requires `--approve`. Capability expansion can require fresh consent. Explicit disable persists across updates. `enable --project PATH` scopes consent to a project; omitting it uses user scope. `disable --project PATH` is accepted/reported, but the current CLI disable operation is user-wide. The desktop presents these states: | State | Meaning | | --- | --- | | `enabled` | Enabled in the registry; execution still requires admission. | | `needs-consent` | Review and approve the requested capabilities. | | `disabled` | Disabled by the user. | | `failed` | A failure is reported; inspect the last failure message. | The CLI additionally separates enablement (`inactive`, `enabled`, `disabled`) from consent (`inactive`, `needs-consent`, `granted`, `disabled`) and reports worker availability. A strict build lists the bundled catalog as disabled, with consent `unavailable` and worker `excluded`. ## CLI reference These are the command shapes from the plugin help renderer ([`render.rs`](../../crates/dctx-cli/src/plugin/render.rs)) and [`parse.rs`](../../crates/dctx-cli/src/plugin/parse.rs): ```text dctx plugin search [query] [--refresh] [--json] dctx plugin install <owner/repo>[@version] [--enable --approve] [--json] dctx plugin install --url <https-url> --id <publisher/name> [--json] dctx plugin install --file <bundle> --id <publisher/name> [--json] dctx plugin list [--json] dctx plugin info <id> [--json] dctx plugin enable <id> [--project <path>] [--approve] [--json] dctx plugin disable <id> [--project <path>] [--json] dctx plugin remove <id> [--json] dctx plugin update [<id>] [--version <version>] [--check] [--json] dctx plugin verify [<id>] [--refresh-trust] [--json] dctx plugin run <id> -- <args> dctx git <status|protect> ``` `dctx plugin`, `dctx plugin help`, `--help` and `-h` show plugin help. Search accepts one query argument; quote phrases. Search and list use cached metadata; `search --refresh` requests a fetch. List and help start no worker, fetch nothing and do not create a project `.dctx/` directory. Install accepts exactly one source: repository locator, HTTPS manifest URL or offline bundle. URL/file sources require `--id`; the parser also accepts `--enable --approve` with those sources. `update --check` reports a candidate without downloading; omitting the ID in update/verify selects the bundled plugin. `verify --refresh-trust` requests a revocation freshness check. Bundled updates come with the containing CLI/app release. `remove` masks the bundled copy when applicable. The current product's offline limits still apply to these commands. `run` requires the `--` separator. The Git alias rejects that separator. The parser recognizes `--json` for plugin and alias requests, including `run`, and strips it before forwarding plugin arguments. ## Desktop: Settings > Plugins Open **Settings > Plugins** to inspect bundled/installed source, version, state, requested capabilities and the last failure. **Refresh plugins** reloads the list. **Enable** and **Disable** call the host management API. **Grant consent** opens a review dialog with plugin ID, version, artifact SHA-256, capability descriptions and exact grants/bounds. **Confirm grant** records user-wide consent for all projects; **Cancel** closes the dialog. **Check for update** reports cached information and explicitly states that online discovery is unavailable. These behaviors are implemented in [`plugins.ts`](../../apps/dctx-desktop/src/plugins.ts); opening settings does not itself execute plugin code or fetch from a network. ## Strict build The [`dctx` library](../../crates/dctx/Cargo.toml) includes the optional `plugin-runtime` feature in its defaults. Hosts requiring the engine without that runtime must disable defaults and select `pack`, `map`, `templates`, `fs`, `segments`, `cache` as needed. The runtime adds the host, platform and protocol dependencies; sessions still require an explicit host. For the [CLI](../../crates/dctx-cli/Cargo.toml), select `--no-default-features --features strict` when building. Cargo features are additive: selecting `strict` alone leaves defaults enabled. This composition excludes `dctx-plugin-host`, `dctx-plugin-platform` and `dctx-plugin-git` from normal dependencies. Management metadata/protocol/distribution code remains; strict does not mean that every crate whose name contains `plugin` disappears. ## Trust and signatures Distribution verifies detached Ed25519 signatures over domain-separated exact manifest/index bytes, checks SHA-256 artifact integrity, and uses pinned publisher keys, revocation freshness and rollback checks. A key downloaded beside an artifact is not an independent trust anchor. Verification does not grant capabilities or establish confinement. The production verifier never signs or generates keys; signing belongs only in separate release tooling (test fixtures use test keys). **Unverified:** a completed production release signing tool in this checkout; the design describes it as separate work. The product CLI currently supplies no index key and no TLS network adapter. ## What is not yet available - Qualified native plugin launch on any OS. Linux has restricted-process building blocks, but arbitrary third-party ELF launch remains unsupported; macOS lacks the reviewed Seatbelt/initial-exec composition; Windows and other targets are unsupported. The platform provider also refuses bundled launch and the Git recipe. A consent record cannot bypass these admission failures. - Online discovery, downloads and updates in the current product wiring. Search can inspect cached metadata and the distribution engine supports verified offline bundles, but network refresh needs a configured trust key and network adapter. The desktop explicitly reports offline update discovery. - Public plugin publication through this CLI. There is no `plugin publish` command. The default discovery URL is `https://example.invalid/dctx/index.json`; a live public registry/release publication is **unverified**. Local index tooling and signed fixture tests do not establish public availability. Sources: [plugin design](../design/PLUGINS.md), [native platform limits](../../crates/dctx-plugin-platform/README.md), [Ed25519 verification](../../crates/dctx-plugin-distribution/src/domain/signature.rs), and the [crate map](../CRATE-MAP.md). </FILE_CONTENT_END ID="F029"> <FILE_CONTENT_START ID="F032" PATH="docs/research/stability-20261105/REPORT.md" LINES="144"> <!-- SPDX-License-Identifier: Apache-2.0 --> <!-- SPDX-FileCopyrightText: 2026 Eris Margeta --> # STAB-01: byte stability on `0495f5f` Measured **2026-11-06 UTC** on Linux from commit `0495f5f87717df5385209d306b92328a8cd96cf6`. The directory retains its original evidence date. No engine changes were made. | Measurement | Text | JSON | |---|---:|---:| | Answers identical after unrelated edit | 33/33 | 33/33 | | Answers identical over five separate invocations | 33/33 | 33/33 | | Baseline -> post-edit common-prefix ratio, minimum / mean | 1.0 / 1.0 | 1.0 / 1.0 | | Consecutive same-request transitions, five per case | 165 | 165 | | Same-request M7, minimum / mean | 1.0 / 1.0 | 1.0 / 1.0 | | Consecutive changing-question transitions | 195 | 195 | | Changing-question M7, minimum / median / mean | 0.007795889 / 0.107142857 / 0.214830257 | 0.008776458 / 0.067594433 / 0.182446794 | | Changing-question M7, total prefix bytes / total current bytes | 0.061846978 | 0.079892615 | All **405 CLI invocations exited 0**, with empty stderr: 396 measurement invocations (66 cases × six runs), three target-resolution invocations, and six snapshot controls. All 33 default text headers were exactly `# <place> <verb>`; all 33 default JSON answers omitted snapshot, generation and `freshness.age_s`. `--meta --json` controls confirmed that each corpus's snapshot changed after the edit. ## Protocol and pins The original producer is [`phase_query.py`](../trail-code-2026-10/scripts/phase_query.py), with byte comparisons in [`aggregate.py`](../trail-code-2026-10/scripts/aggregate.py), section 7. It runs five warm queries, appends a comment to an unrelated file in another directory, reruns queries, and restores the file. Its original evidence remains at [`data/stability.csv`](../trail-code-2026-10/data/stability.csv). The original `/path/to/workdir/dctx-vs-trail` host tree is absent. The repository contains the scripts and historical results, but no original seven-corpus checkout set or the host's `scripts/corpora.json`. Checked alternate `bench3` and `perf-20261101` corpora paths were also absent. This run uses the documented fallback: three corpora extracted exclusively from tracked files at the pinned current commit. No fetch or network access was used. The new denominator differs from the historical 0/63; Trail-Code's historical 59/70 was not rerun. | Corpus | Exact tracked prefix extracted | Files | Symbol / file | Unrelated file edited | |---|---|---:|---|---| | parser-mixed | `crates/dctx-map-parse/tests/fixtures/` | 17 | `helper`, `rust/src/support.rs` | `ts/module.ts` | | lexer-go | `crates/dctx-lex-go/` | 19 | `Add`, `tests/fixtures/basic.go` | `src/lib.rs` | | map-query | `crates/dctx-map-query/src/` | 30 | `render_answer_at`, `adapters/output.rs` | `domain/ranking.rs` | Each prefix is copied in full using `git ls-tree -r --name-only <pin> -- <prefix>` and `git show <pin>:<path>`, retaining paths relative to the prefix. Every file's size and SHA-256, and the CLI binary SHA-256, are in [`corpora.json`](corpora.json). Work copies and isolated cache/config directories live in a disposable `/tmp` directory. The live worktree's corpus files are never edited. The original applicable map query shapes are retained: `find --limit 10`, inbound `neighbors --edge calls` at depths 1 and 2, outbound neighbors, `map --depth 2 --limit 40`, `read`, and `explain`. Each now runs in **both** formats. The current bounded `skeleton`, `grep`, `hubs`, and `path` verbs add four shapes per corpus, again in both formats: 11 × 2 × 3 = 66 cases. Stable target IDs are resolved by `find --json --limit 40`, matching exact path and symbol. `path` tests a file's containment edge to that symbol. `grep` is confined to the target file. Default budgets and default output are used, without `--meta` in the measured answers. There are five warm sweeps, separated by 1.05 seconds, then a sixth sweep after appending exactly `\n// STAB-01 unrelated comment\n` to the named unrelated file. The comment is outside declarations and contains none of the queried names. It changes snapshot identity without changing the selected declarations, calls, search hits or hub counts. Original bytes are restored in a `finally` block and verified. Configuration and caches are isolated using `XDG_CONFIG_HOME`, `XDG_CACHE_HOME` and `DCTX_CACHE_DIR`; inherited `DCTX_*` overrides are removed. Every JSON case has records except outbound neighbors for the two leaf functions `helper` and `Add`. Their empty answers are included. All three inbound-neighbor cases have records, all paths are found, and `render_answer_at` has nine returned outbound neighbors plus eleven more in the bounded page. No cursor pages were followed. Whole-graph `export` has no unrelated graph input and is outside this bounded-answer protocol. The historical legacy snapshot overview, Trail-only grep and no-refresh shapes are outside the map-answer comparison. ## M7 and acceptance limits For each transition, M7 = longest common **byte** prefix of previous and current stdout / **current** stdout byte length. Both block lengths and the prefix length are stored in [`turn-prefixes.csv`](turn-prefixes.csv); there are no empty blocks. No whitespace, JSON fields, paths, timestamps or newlines are normalized. The same-request trace is each case's five warm answers followed by its post-edit answer: five consecutive transitions per case, 330 total. The additional changing-question trace uses actual invocation order, separately per corpus and format: the 11 query shapes in the order above, repeated over six sweeps; 65 transitions per stream, 390 total. Text and JSON are separate context-block streams. These are recorded tool-answer traces, with one answer treated as one injected block; there is no provider cache-hit or task-acceptance measurement. The local unrelated-edit and five-run JSON gates pass. The low changing-question ratios show why this result cannot establish §12.1's T0–T3 invariant or its recorded tier-context M7 ≥ 0.9 gate. Tier layering remains **target**. No cross-platform, thread-count, changed-answer-content, or full original benchmark gate is claimed. No unrelated-edit instability was observed, so there is no instability reproducer. The three text `read` pages actually include their selected source bodies. Text `explain` still consists of header and id/kind/path, so §11's richer text-page contract remains a target. Other text fields, JSON compaction and provenance-trailer contracts were not promoted to landed by this measurement. ## Exact commands and exits Run from `/path/to/workdir/codex/STAB-01R`: ```sh export PATH=$HOME/.cargo/bin:$PATH export CARGO_TARGET_DIR=$PWD/.target-stab cargo --offline build --locked -p dctx-cli > /tmp/stab-01-build.log 2>&1 ``` Exit **101**: configured `sccache` failed with `Operation not permitted`, before compilation. A retry after `unset RUSTC_WRAPPER`, with output redirected to `/tmp/stab-01-build-no-wrapper.log`, also exited **101**: Cargo's user config still specified `build.rustc-wrapper = "sccache"`. ```sh export PATH=$HOME/.cargo/bin:$PATH export CARGO_TARGET_DIR=$PWD/.target-stab export RUSTC_WRAPPER= cargo --offline build --locked -p dctx-cli > /tmp/stab-01-build-direct.log 2>&1 python3 docs/research/stability-20261105/measure.py > /tmp/stab-01-measure.log 2>&1 python3 docs/research/stability-20261105/verify.py git diff --check ``` Exits: build **0**; measurement **0**; independent raw-data audit **0**; `git diff --check` **0**. Build logs and [`measurement.txt`](measurement.txt) are preserved here. [`commands.md`](commands.md) lists every query shape and setup/control command; [`runs.jsonl`](runs.jsonl) records all 405 exact argv arrays, shell-quoted commands, working directories, environment overrides, exits, full stdout/stderr, byte counts and SHA-256 hashes. `measure.py` records a fresh run only when no `runs.jsonl` exists; use a fresh copy of the evidence directory to repeat it. [`stability.csv`](stability.csv) is the new measurement. The adjacent [`stability-original.csv`](stability-original.csv) is a byte-for-byte copy of the historical CSV, SHA-256 `46b54db2fb469dc4df70eaa0bf22b458a8089f437cdee3294efe071314280266`. Both files are retained to distinguish the new measurement from the unchanged historical source. </FILE_CONTENT_END ID="F032"> <FILE_CONTENT_START ID="F034" PATH="docs/research/trail-code-2026-10/REPORT.md" LINES="554"> <!-- SPDX-License-Identifier: Apache-2.0 --> <!-- SPDX-FileCopyrightText: 2026 Eris Margeta --> # dctx vs Trail-Code: head-to-head benchmark (October 2026) Isolated, reproducible comparison of two code-context tools for coding agents on seven real corpora and one synthetic adversarial corpus. Every number below comes from `data/raw/*.jsonl` and can be regenerated with `scripts/`. Where Trail-Code is better, this report says so plainly. - **dctx** at commit `17dff0b454c24f43848abad1c88ea982e02731f7` (branch `internal`), `dctx-cli v0.25.0`, agent interface `dctx map <map|find|neighbors|explain|read>`. - **Trail-Code** `@trailhq/trail-code@0.23.1` from npm (repository HEAD `b1211efd`, whose `package.json` is also 0.23.1), CLI `trail`. ## 1. Summary | Area | Result | |---|---| | Call graph (callers, depth 1) | **Trail-Code wins decisively.** Trail precision 0.94 to 1.00, recall 0.10 to 0.96 per corpus. dctx returns **no call or import edges at all** (recall 0 on 140 targets): the CLI facade only emits `contains` edges. | | Task-level answers (70 agent questions) | Trail 122/140 points, 312/354 gold facts in 88.7k tokens. dctx 69/140, 169/354 in 500k tokens (480k of them from the unbounded legacy tree used as the only overview). Without the overview question dctx uses 19.2k tokens for 137/322 facts (7.15 facts/1k tokens) versus Trail 57.0k for 284/322 (4.98 facts/1k): dctx is terser, Trail answers about twice as much. | | Footprint | **dctx wins.** One 9.2 MB binary (libc, libm, libgcc_s) versus 405.6 MB of `node_modules` (8,567 files, 50 package versions) plus a Node runtime. | | Cold index | **dctx wins** on all seven corpora: 0.09 to 6.05 s versus 2.44 to 94.9 s (2.8 to 69 times faster); peak RSS 8 to 567 MiB versus 181 to 2,111 MiB. Trail's index is smaller only on core (65 MB versus 158 MB). | | Warm query latency | **dctx wins** on small and medium repos (30 to 260 ms versus 0.6 to 1.4 s; Node startup sets Trail's floor near 0.6 s). On the largest Rust corpus dctx re-reads a 158 MB generation per process (1.45 s, 370 MiB per query) and Trail's `callers` is faster (0.83 s). | | Freshness | **Tie on correctness**: both see unstaged, untracked and staged edits and drop reverted symbols. Trail also adds the caller edge to the new function; dctx cannot. dctx's first query after an edit costs a full re-index (core: 7.5 s), and every edit adds a full new generation to the cache (core: 158 MB to 946 MB). | | Cache-friendliness | **Trail wins.** Trail text outputs are byte-identical across runs and across unrelated edits. Every dctx answer starts with a header containing the snapshot digest, so any edit anywhere changes byte 21 to 50 of every answer; dctx JSON is never byte-identical twice (`age_s`). | | Bounding | **dctx wins for map verbs** (hard 2,000-token cap, never exceeded; budgets below the minimum record size are refused with exit 1). Trail has no budget flag; single answers reached 142 KB (40.6k tokens). dctx's legacy tree and `pack` are unbounded (974 KB tree on django; 8.7 MB pack). | | Privacy / network | **dctx wins.** Zero sockets in every audited dctx run and no writes to the repository in map mode. Trail does a daily npm version check that ignores `DO_NOT_TRACK`, records an install telemetry event in `postinstall` and tries to send it, and modifies `.gitignore` and adds `.ignore` on every `trail build`. dctx `pack` printed a fake `.env` secret; Trail never read `.env`. | | Language breadth | Trail parses 23 languages, including Scala, Elixir, Lua, OCaml, Zig, Dart, Solidity and Vue; dctx parses none of those. dctx adds structure for Markdown, JSON, TOML and YAML, which Trail ignores. | ## 2. Methodology ### Host, isolation, contention - VM `build-host`: 32 vCPU Intel Xeon E5-2680 v2 @ 2.80 GHz, 94 GB RAM, Debian 13, kernel 6.12.111, Node v24.22.0, npm 11.19.1, rustc/cargo 1.99.0 (`data/env.txt`). - The VM was also running an unrelated build and mutation batch. Every benchmark command was pinned with `taskset -c 24-31` (8 CPUs). The other batch was not pinned, so it could share those CPUs. 1-minute load average across the 3,398 measured runs: min 1.04, median 2.31, p95 8.46, max 16.03 (each row in `data/raw/*runs.jsonl` records load before and after; `phases.jsonl` records each phase). The ripgrep and pocketbase query phases ran at load 8 to 10, so treat their Trail `find` times (1.2 to 1.3 s) as contention-affected. - Both tools ran as the dedicated unprivileged user `dctxbench`, with `HOME`, npm prefix, npm cache, `XDG_CACHE_HOME` and `DCTX_CACHE_DIR` inside `/path/to/workdir/dctx-vs-trail`, through `scripts/benv` (`env -i`, then `sudo -u dctxbench unshare -rn`, then `taskset`). After installs, clones and builds, every measured command ran in a new network namespace with only a down loopback. - `DO_NOT_TRACK=1` (Trail's documented opt-out, `dist/telemetry/gate.js`) was set for every measured Trail run except the two deliberate "telemetry on" network audits. - Timing: GNU time 1.9 (`/usr/bin/time -v`, 10 ms resolution) records wall, user+sys CPU and peak RSS for the tool process tree. Warm queries are medians of 5 runs, cold runs medians of 3. - Output size: raw stdout bytes and `ceil(bytes / 3.5)` estimated tokens for both tools (identical to dctx's own `ceil(2*bytes/7)`). This is an estimate, not a tokenizer. - Page cache was not dropped, to avoid disturbing the co-tenant batch. "Cold" therefore means "no tool index or cache", not "cold disk". ### Builds and versions - dctx: source rsynced from the workstation (no `target/`), built with `cargo build --release --locked -p dctx-cli -j 8` without a compiler cache: 98.7 s wall, 389 s user CPU. Binary: 9,207,072 bytes, sha256 `26c3cb70...cbce`. `ldd`: `libgcc_s`, `libm`, `libc`, `ld-linux` only. - Trail-Code: `npm install --save-exact @trailhq/trail-code@0.23.1` (39.96 s). npm 11.19 printed "install scripts not yet covered by allowScripts" warnings but still ran them (13 packages, including Trail's own `postinstall` and `node-gyp` builds; Node headers were downloaded into `~/.cache/node-gyp`). ### Corpora (pinned) | Corpus | Language | Pin | Tracked files | |---|---|---|---| | flask | Python | tag 3.1.3, `22d92470` | 235 | | ripgrep | Rust | tag 15.2.0, `e89fff89` | 222 | | pocketbase | Go + JS | tag v0.40.5, `6f370ea7` | 924 | | trailcode (Trail-Code repo) | TypeScript | `b1211efd` | 380 | | dctx | Rust (+ fixtures in 15 languages) | `17dff0b4` | 1,749 | | django | Python | tag 6.1.2, `2212534b` | 7,071 | | core (private Rust repository) | Rust | `f5f2f48b` | 3,190 | | adversarial (generated) | mixed | `scripts/gen_adversarial.py` | see section 10 | `core` was copied without `target/` and `corpus/`; its `.agent/worktrees/` (copies of the tree) was also removed. Its raw outputs, symbol names, paths and source lines are **redacted** from `data/` (`scripts/redact_private.py`); only numbers are published. ### Gold sets and scoring - **Targets.** `scripts/select_targets.py` picks 20 definitions per corpus with a fixed seed: 4 hubs (unique name, many calls), 4 rare (1 to 3 calls), 4 receiver-called methods, 4 colliding names (2 to 6 definitions), 4 interface/trait methods. Selection uses the independent oracle in `scripts/goldlib.py`, not either tool. - **Oracle.** Comments and strings are blanked (a cross-line state machine for Rust and Go, per-line for JS/TS, triple-quote aware for Python). A line is a call site of `N` only if `N` is directly followed by an argument list and the line is not a definition. Each site is bound to a definition by scope rules (same file or package, explicit import, `self`/`this`, `Type::`); receiver calls to names that also exist on standard-library types, and anything else unresolvable, are **ambiguous** and excluded from both precision and recall. Interface/trait targets are scored at name level: every site bound to some in-repo definition of the name, plus `self` calls. - **Adjudication.** A Trail `calls` hit is a true positive if its span contains a gold site of the target, unjudged if it only contains ambiguous sites, and a false positive otherwise. Recall counts gold sites inside any reported hit. Collisions were spot-checked by hand (all 28 collision targets: sample sites listed in `data/targets/*.targets.json`). The hand check found one oracle bug: a `/*` inside a Rust multi-line doc string started a fake block comment. After the fix the gold was rebuilt for the **same** targets (`scripts/regold.py`; one target changed, ripgrep `unwrap_switch`, 61 to 69 sites), and the ripgrep accuracy and task phases were rerun. The earlier rows are kept in `data/raw/*.pre-regold`. A remaining known oracle gap: calls inside Python f-strings and JS template literals are blanked, which made one true Trail hit (flask `dumps`) count as a false positive. - **Tasks.** `scripts/phase_tasks.py` builds 10 questions per corpus from the same oracle with fixed command sequences per tool. Facts are scored by presence in the outputs (JSON string values are also searched); caller facts must come from a caller/impact answer and need the caller's path and one of its call-line numbers. Score per question: 2 if at least 80% of facts are present, 1 if any, 0 otherwise. ## 3. Footprint | | dctx | Trail-Code | |---|---|---| | Install | one binary, 9,207,072 bytes | `node_modules` 405,601,700 bytes, 8,567 files | | Dependencies | 46 external crates in `cargo tree -e normal` (see TC-F11) | 50 package versions (47 names) in `npm ls --all`; largest: `tree-sitter-wasm` 128 MB, `@trailhq/trail-code` 129 MB (bundled grammars), `tree-sitter-swift` 73 MB, two LLM-provider SDKs 34 MB and 14 MB (used only by `--deep`) | | Runtime | libc, libm, libgcc_s | Node >= 20 plus native addons | | Install side effects | none | `postinstall` records an anonymous install event and spawns a detached flush; `~/.graft/telemetry.json` and `~/.graft/update-check.json` created at install | ## 4. Indexing (section 2 of the brief) Cold = new copy, no tool state, median of 3. dctx has no index command, so its cold run is the first `dctx map find main` with an empty `DCTX_CACHE_DIR`. The Trail cold run is `trail build .`. No-op = repeat with nothing changed (dctx: same query; Trail: `trail build .` again and `trail build --check .`). | Corpus | dctx cold s (CPU s) | Trail cold s (CPU s) | dctx peak RSS MiB | Trail peak RSS MiB | dctx cache MB | Trail index MB | dctx no-op s | Trail no-op build s | Trail `--check` s | |---|---|---|---|---|---|---|---|---|---| | flask | **0.09** (0.08) | 3.45 (3.88) | **8** | 181 | **0.85** | 4.39 | **0.04** | 0.88 | 3.29 | | ripgrep | **0.45** (0.42) | 2.44 (3.40) | **18** | 282 | **1.77** | 8.36 | **0.05** | 1.35 | 1.97 | | pocketbase | **0.72** (0.71) | 49.45 (51.42) | **39** | 969 | **6.69** | 41.83 | **0.17** | 2.65 | 49.52 | | trailcode | **0.31** (0.30) | 17.83 (18.65) | **17** | 452 | **3.56** | 13.70 | **0.08** | 1.58 | 18.67 | | dctx | **2.42** (2.38) | 9.74 (13.96) | **64** | 834 | **14.88** | 42.68 | **0.27** | 3.81 | 7.90 | | django | **2.48** (2.46) | 94.89 (97.55) | **92** | 2,111 | **23.30** | 167.48 | **0.81** | 9.15 | 86.46 | | core | **6.05** (7.02) | 16.88 (21.43) | **567** | 916 | 157.70 | **64.71** | **1.34** | 4.66 | 13.82 | Notes: - core's dctx cost is dominated by configuration extraction. `--profile` on a cold run: parse/lex 3.39 s, canonicalize/seal 1.43 s, persist 0.97 s; the slowest file is a 6.7 MB JSON test fixture that produced 235,842 symbols. The 158 MB generation is 2.9 times the 54 MB working tree (TC-F07). - Trail's `build --check` (the CI freshness check) costs as much as a full build on pocketbase and django. - Trail writes its index into the repository: `graft/` plus a modified `.gitignore` and a new `.ignore` on every corpus, or `.trail/cache/` when the repo already has `.trail/` (Trail's own repo). dctx map writes nothing into the repository and nothing into `HOME` (verified by full manifests before and after). ## 5. Query latency and output size (section 3 and 4) Warm medians of 5 (wall seconds; bytes of the answer). Command mapping: find = `dctx map find N --limit 10` / `trail ask N`; callers = `dctx map neighbors <id> --dir in --edge calls` / `trail callers N`; outline = `dctx map map FILE --depth 2 --limit 40` / `trail skeleton FILE`; read = `dctx map read <id> --json` / `trail ask N --source --full -n 1`; overview = legacy `dctx . -t` (the map verbs have no root overview, TC-F05) / `trail map`; grep = none / `trail grep 'N\('`. | Corpus | find dctx | find Trail | callers dctx | callers Trail | outline dctx | outline Trail | read dctx | read Trail | overview dctx | overview Trail | grep Trail | |---|---|---|---|---|---|---|---|---|---|---|---| | flask | 0.03 s / 848 B | 0.69 s / 917 B | 0.03 / 104 (empty) | 0.63 / 476 | 0.03 / 1,327 | 0.63 / 2,980 | 0.03 / 1,472 | 0.68 / 1,622 | 0.04 / 22,537 | 0.64 / 3,925 | 0.65 / 3,244 | | ripgrep | 0.06 / 217 | 1.27 / 1,371 | 0.06 / 107 (empty) | 0.67 / 2,801 | 0.05 / 1,700 | 0.66 / 3,935 | 0.05 / 897 | 0.85 / 1,057 | 0.08 / 21,972 | 0.71 / 8,883 | 0.69 / 3,213 | | pocketbase | 0.17 / 993 | 1.18 / 1,252 | 0.20 / 110 (empty) | 1.04 / 611 | 0.17 / 1,087 | 0.72 / 1,226 | 0.17 / 780 | 1.19 / 1,902 | 0.22 / 80,655 | 0.79 / 5,297 | 0.96 / 5,019 | | trailcode | 0.08 / 1,405 | 0.90 / 1,792 | 0.08 / 109 (empty) | 0.67 / 1,624 | 0.08 / 1,740 | 0.66 / 4,166 | 0.08 / 1,691 | 0.92 / 2,332 | 0.41 / 30,347 | 0.67 / 1,687 | 0.74 / 3,476 | | dctx | 0.26 / 222 | 1.40 / 3,020 | 0.26 / 105 (empty) | 0.79 / 6,790 | 0.26 / 1,653 | 0.76 / 4,329 | 0.26 / 1,452 | 1.41 / 2,643 | 0.24 / 199,371 | 2.81 / 34,030 | 1.38 / 8,375 | | django | 0.82 / 196 | 3.28 / 1,093 | 0.82 / 107 (empty) | 1.39 / 3,116 | 0.81 / 1,719 | 1.32 / 2,575 | 0.81 / 835 | 3.30 / 876 | 0.98 / 974,082 | 1.52 / 4,151 | 5.43 / 6,249 | | core | 1.45 / 534 | 1.65 / 3,817 | 1.45 / 106 (empty) | **0.83** / 1,366 | 1.45 / 1,600 | **0.81** / 1,196 | 1.44 / 1,914 | 1.69 / 4,159 | 0.70 / 350,226 | 10.00 / 52,978 | 1.50 / 4,368 | - dctx warm latency grows with repository size because every process re-opens and loads the whole generation (core: 370 MiB RSS for any query). Trail's floor is Node startup (~0.6 s, ~100 MiB RSS). - dctx text mode is thin: `find` prints `id kind path` without line numbers, and `read`/`explain` in text mode print only the id line (152 to 247 bytes, no source and no signature). Source needs `--json` (TC-F04). - dctx `--json` repeats thirteen keys per record, many of them `null`. Under the same default budget a JSON `find` returned 4 records where the text `find` returned 10 (flask, `dispatch_request`). - dctx cold query (empty cache, includes indexing, median of 3): flask 0.09 s, ripgrep 0.46 to 1.41 s, pocketbase 0.72 s, trailcode 0.31 s (`data/queries_cold_dctx.csv`). Trail cannot answer without a graph ("no graph found ... run `trail build` first"), so its cold first answer is the cold build plus a query. - Trail prepends a banner to `callers`, `skeleton`, `grep`, `map` and source answers. The banner estimates "tokens saved" and instructs the agent to tell the user the total each turn: ~310 bytes (~89 tokens) per call, 6.3% of all Trail warm-query bytes and 54% of the `callees` answers. ## 6. Freshness and incremental updates (section 2) Probe: append a new function that calls the hub target to its file (unstaged), then add a new untracked file, then `git add` it, then revert everything (`data/freshness.csv`). | Corpus | dctx: new fn found / first query s | Trail: new fn found / first query s | Trail caller edge to new fn | Untracked file found (dctx / Trail) | Staged found | Stale after revert | |---|---|---|---|---|---|---| | flask | yes / 0.11 | yes / 1.06 | yes | yes / yes | yes / yes | no / no | | ripgrep | yes / 0.42 | yes / 1.43 | yes | yes / yes | yes / yes | no / no | | pocketbase | yes / 0.76 | yes / 2.95 | yes | yes / yes | yes / yes | no / no | | trailcode | yes / 0.32 | yes / 1.93 | yes | yes / yes | yes / yes | no / no | | dctx | yes / 2.31 | yes / 4.50 | yes | yes / yes | yes / yes | no / no | | django | yes / 2.70 | yes / 11.30 | yes | yes / yes | yes / yes | no / no | | core | yes / 7.48 | yes / 5.45 | yes | yes / yes | yes / yes | no / no | - Both tools are correct on every freshness check, including uncommitted, unstaged and untracked edits. dctx never reports the caller edge because it has no call edges. - dctx re-indexes everything after any change: the first query after an edit costs about the cold time (core 7.48 s versus 1.45 s warm; django 2.70 s versus 0.82 s). Trail re-parses only what moved (django 11.3 s versus a 95 s cold build). - Each changed snapshot adds a complete new dctx generation. After the query and freshness phases, the core cache held six 158 MB generations (946 MB); three of them were byte-identical copies of the original snapshot. `dctx cache status` reported 473 MB reclaimable, and `dctx cache gc --dry-run` reclaimed 0 bytes (`blockers: unlink_grace`). Total dctx cache at the end of the run (all corpora including the adversarial ones): 1.36 GB. Trail's index sizes stayed constant. ## 7. Call-graph and definition accuracy (section 5) Definition-level targets (hub, rare, receiver, collision; 16 per corpus), micro-averaged over call sites. Interface/trait targets are scored at name level separately. Per-target rows: `data/accuracy_targets.csv`. Misses and false positives: `data/raw/accuracy.jsonl` (redacted for core). | Corpus | Gold sites | Trail precision | Trail recall | dctx recall | Interface name-level recall Trail / dctx | Find-def rank 1: dctx `find` / Trail `ask` | Def in results: dctx / Trail `ask` | |---|---|---|---|---|---|---|---| | flask | 122 | 1.00 | 0.30 | 0 | 1.00 / 0 | 14 / 14 of 20 | 20 / 19 | | ripgrep | 144 | 1.00 (3 unjudged) | 0.68 | 0 | 0.50 / 0 | 13 / 10 | 20 / 12 | | pocketbase | 212 | 1.00 | 0.10 | 0 | n/a (no resolvable sites) | 17 / 8 | 20 / 13 | | trailcode | 105 | 1.00 | 0.96 | 0 | 0.13 / 0 | 14 / 12 | 20 / 14 | | dctx | 328 | 1.00 | 0.52 | 0 | 1.00 / 0 | 14 / 11 | 20 / 15 | | django | 297 | 1.00 | 0.31 | 0 | 0.33 / 0 | 17 / 12 | 20 / 16 | | core | 179 | 1.00 | 0.69 | 0 | 1.00 / 0 | 14 / 12 | 19 / 20 | By category over all corpora (Trail): hub P 1.00 / R 0.42 (1,187 sites), rare 1.00 / 0.93, receiver 1.00 / 0.56, collision 1.00 / 0.86, interface 0.94 / 0.42. dctx: 0 everywhere. - **dctx has no call graph in the shipped CLI.** `neighbors --edge calls` returned empty on all 140 targets; `--edge imports` on module ids was also empty in spot checks (ripgrep, pocketbase). The lexers do extract references (for example `EdgeKind::Calls` in `dctx-lex-*`, `dctx-map-parse/src/adapters/rust.rs`), but the facade index (`crates/dctx/src/index/extract.rs`) only emits `contains` edges, and `dctx-map-resolve` is linked only through `dctx-map-query`. - **Trail is precise but misses a lot on some corpora.** Typical misses: Go methods called through variables (pocketbase `Record.Verified`, 0 of 39; `Record.ValidatePassword`, 0 of 36); Python methods called on module-level objects (`apps.get_app_configs()`, 3 of 69); calls through a re-exported module name (`flask.abort(...)`, 2 of 22); classmethods called on subclasses (`Index.as_view(...)`, 0 of 20). Trail itself says it drops cross-file callers of ambiguous names "rather than guessed". - **Find definition:** dctx `find` ranked the definition first more often (103/140 versus 79/140 for Trail `ask`) and listed it in 139/140 first pages versus 109/140. Trail `callers N` also lists every same-name definition and matched the target definition in 136/140 cases. ## 8. Task-level information efficiency (section 6) Ten questions per corpus (definition and callers, change impact, outline, config key, module exports, source of a method, callees, repo overview, a colliding name, concept search). Questions and facts: `data/targets/*.questions.json`; per-question rows: `data/tasks.csv`, `data/tasks_by_question.csv`. | Corpus | dctx calls / tokens / score / facts | Trail calls / tokens / score / facts | Facts per 1k tokens dctx / Trail | |---|---|---|---| | flask | 15 / 9,227 / 11 of 20 / 30 of 48 | 10 / 5,529 / 16 / 39 of 48 | 3.25 / 7.05 | | ripgrep | 15 / 9,048 / 9 / 16 of 32 | 10 / 25,974 / 13 / 23 of 32 | 1.77 / 0.89 | | pocketbase | 15 / 25,644 / 11 / 27 of 36 | 10 / 4,026 / 18 / 33 of 36 | 1.05 / 8.20 | | trailcode | 15 / 11,625 / 10 / 35 of 64 | 10 / 7,529 / 19 / 59 of 64 | 3.01 / 7.84 | | dctx | 15 / 60,080 / 10 / 21 of 48 | 10 / 15,396 / 19 / 44 of 48 | 0.35 / 2.86 | | django | 15 / 281,264 / 10 / 29 of 70 | 10 / 7,006 / 18 / 63 of 70 | 0.10 / 8.99 | | core | 15 / 103,117 / 8 / 11 of 56 | 10 / 23,231 / 19 / 51 of 56 | 0.11 / 2.20 | | **All** | 105 / 500,005 / **69 of 140** / 169 of 354 | 70 / 88,691 / **122 of 140** / 312 of 354 | 0.34 / 3.52 | | All except overview | 98 / 19,156 / 55 of 126 / 137 of 322 | 63 / 56,989 / 109 of 126 / 284 of 322 | **7.15** / 4.98 | By question type (score out of 14): outline dctx 11 / Trail 14; exports 8 / 14; source 14 / 12; definition and callers 7 / 10; impact 7 / 13; callees 2 / 8; collision 6 / 12; config key 0 / 14 (dctx has no text search); concept search 0 / 12 (multi-word `dctx map find` returned no records); overview 14 / 13 (dctx through the unbounded legacy tree: 480k tokens over seven corpora versus 31.7k for `trail map`). ## 9. Cache-friendliness (section 7) Each warm query ran 5 times, then again after appending one comment line to an unrelated file in another directory (`data/stability.csv`). | Property | dctx | Trail-Code | |---|---|---| | Text output identical over 5 runs | yes (all text verbs) | yes | | JSON output identical over 5 runs | **no**: `freshness.age_s` changes every second | yes | | Identical after an unrelated edit | **no, every answer**: header `# <place> <verb> v1:sha256:<digest>:<bytes> g=<n>` changes; common prefix 21 to 50 bytes | yes for callers, callees, outline, grep, read, text find; `map` banner counts change; `ask --json` scores churn in the 9th to 16th digit | | Absolute paths in output | none in map verbs; legacy `dctx .` prints the absolute path and a timing line | `ask --json` includes absolute paths of `.trail/learnings` files | | Timestamps | `age_s` in JSON | none in answers | | Ordering | stable | stable | ## 10. Robustness and privacy: adversarial corpus (section 10) `scripts/gen_adversarial.py` plants: a non-ignored `.env` with `DCTXBENCH_FAKE_SECRET=sk-test-...`, a gitignored directory and a gitignored `*.secret.py` with unique markers, an un-ignored `node_modules/`, a NUL-containing `.py`, a 50 MB text file, a 5 MB single-line minified JS, a 5 MB generated Python module with 50,000 functions, a 100 KB line, a symlink loop and a symlink escaping the repository, a non-UTF-8 file name, a file name with a space and one with a newline, 200 nested directories, a CRLF file, empty and BOM-only files, and 13 files in languages dctx does not support. Run twice: as a git repository and as a plain directory. Timeout 300 s per command (`data/raw/adversarial.jsonl`). | Check | dctx | Trail-Code | |---|---|---| | Crash or hang | none in map verbs or `pack`; legacy `dctx . -t` exits 1 with `resource limit exceeded: Depth > 128` | none | | Gitignored files (git repo) | not indexed, not in `pack` | not indexed (`trail grep` names the ignored paths in its footer) | | Gitignored files (no `.git`) | **still excluded** (rules read from `.gitignore`) | **indexed**: the gitignored secret value is in `graft/.cache/extract.*.json` and in `trail grep sk-test` output | | `.env` secret | **printed by `dctx pack .`** (not in map answers or the map cache) | never read | | Symlink loop / escaping symlink | not followed | not followed | | `node_modules/` (not ignored) | skipped | skipped | | NUL-containing `.py` | skipped as binary | indexed | | 5 MB minified JS, 5 MB generated `.py` | indexed (last of 50,000 functions found) | skipped | | Non-UTF-8 file name | skipped silently | skipped | | Newline in file name | skipped | indexed | | CRLF file | correct outline, read and spans | correct skeleton and callers | | 200-deep nesting | indexed by map | indexed | | Unsupported languages (13 files) | 0 indexed | 8 indexed (Zig, Elixir, Lua, OCaml, Scala, Dart, Solidity, Vue) | | Cost on this corpus | first query 2.6 s, 262 MiB RSS; cache 45.9 MB | build 1.5 s, 277 MiB RSS; index 0.13 MB | | Repository writes | none (legacy `dctx .` writes `.dctx/`) | `.gitignore` modified, `.ignore` added | ## 11. Network and telemetry audit `strace -f -e trace=socket,connect,sendto,sendmsg,bind` inside the network namespace (`data/raw/network.jsonl`). | Run | Sockets | Notes | |---|---|---| | `dctx map find`, `dctx pack .`, `dctx plugin list` | 0 | no socket syscalls at all | | `trail build .` (telemetry on, and with `DO_NOT_TRACK=1`) | 0 | | | `trail callers` with the daily update-check stamp expired, **with and without `DO_NOT_TRACK=1`** | 30 | resolves `registry.npmjs.org` through systemd-resolved's varlink socket (which works from inside a network namespace), then tries TCP 443 on 104.16.x.34 and 2606:4700::6810:x; connects fail with `ENETUNREACH` | | any Trail command with telemetry on, offline | 0 | events are queued in `~/.graft/telemetry-queue.ndjson`: app version, OS, arch, Node major, command, a random `repo_id` UUID, file-count bucket, languages, duration bucket | | `npm install` (network allowed) | n/a | `postinstall` recorded an install event and spawned a detached flush (`flushedAt` set in `~/.graft/telemetry.json`); delivery cannot be confirmed | Trail's documented telemetry gates (`DO_NOT_TRACK`, CI, `trail telemetry disable`) did stop the usage pings. They do not gate the update check. ## 12. Files written by `trail init` (flask, `-y`) - Repository (agent names replaced by `<agent>`): `.<agent>/settings.json`, `.<agent>/settings.local.json`, `.github/<agent>-instructions.md`, `.trail/.gitignore`, `.trail/README.md`, `.trail/hook.cjs`, `.trail/statusline.cjs`, the index under `.trail/cache/` (90 files). - `HOME` (machine-wide): `~/.<agent>/settings.json` (SessionStart, UserPromptSubmit, PostToolUse, Stop and SessionEnd hooks), `~/.<agent>/skills/trail/SKILL.md`, `~/.<agent>/helpers/graft-hooks.cjs`, `~/.trail/README.md`, `~/.trail/install.json`, `~/.trail/repos/index.json`, `~/.trail/repos/known.json`. `--dry-run` lists all of them first; `--no-global` skips the home directory. - `trail uninstall -y` removed the repository wiring and the `~/.<agent>` files, but left `.trail/README.md`, `.trail/.gitignore` and the four `~/.trail/` files behind. - dctx has no init step. `dctx map` wrote nothing into the repositories or into `HOME`. ## 13. Bounding (section 8) - dctx map verbs: `--budget` 1..2000 (explain up to 1000) and `--limit` up to 40 are enforced. All 49 budgeted requests that returned output stayed within budget, as did every broad query at the 2,000-token cap. The other 35 of 84 budgeted requests (budgets 20 and 100) failed with exit code 1 ("budget too small: needs at least 102 bytes") instead of returning a shorter page (TC-F09). Worst map answer on any corpus: 6,996 bytes (1,999 tokens). - dctx outside map: `dctx . -t` wrote 974,082 bytes (278k tokens) for django and failed on the deep tree. `dctx pack .` printed 1.59 MB for flask and 8.67 MB for the adversarial corpus to stdout. - Trail has no budget option. Largest single answers: `skeleton` of a 140 KB generated `types.d.ts` 142,197 bytes (40.6k tokens); `ask --source --full -n 50` 70,466 bytes; `map --max-dirs 100000` 53,870 bytes on core (9.9 s). `grep` is capped internally (15 to 22 KB even for `grep e`), and `ask -n 1000` returned at most 2.2 KB. ## 14. Language coverage (section 9) `data/coverage.csv`: Trail's numbers come from its full graph; dctx's from a seeded sample of up to 12 files per extension (`dctx map map FILE --depth 1 --limit 1`). - Source files: both tools give symbols to 83 to 100% of sampled `.py`, `.rs`, `.go` and `.ts` files (the rest are empty modules and `__init__`-style files). Trail gave symbols to 2,010 of 2,919 django `.py` files, 1,283 of 1,420 core `.rs`, 450 of 457 pocketbase `.go`, 292 of 316 trailcode `.ts`. - JavaScript: Trail indexed 16 of 111 django `.js` files and 177 of 251 pocketbase `.js` files (vendored and large files skipped); dctx produced symbols for 10 of 12 and 8 of 12 sampled files. - Docs and config: dctx gives structure to `.md`, `.json`, `.toml`, `.yaml` and `.yml` (for example 12 of 12 sampled dctx `.json` and `.toml`); Trail gives none. - Language list: Trail claims 23 languages and indexed 8 of the 13 extra languages in the adversarial corpus. dctx documents 15 language families and indexed none of those 13. ## 15. Where dctx wins / where Trail-Code wins / ties **dctx wins** - Footprint: 9.2 MB static-ish binary versus 405.6 MB of Node packages; no install scripts. - Privacy: no sockets in any run; no repository or home writes in map mode; `.gitignore` honoured even without `.git`; gitignored secrets never indexed. - Cold index: 2.8 to 69 times faster and 1.6 to 27 times less peak memory on all seven corpora. - Warm latency on small and medium repositories: 30 to 260 ms versus 0.6 to 1.4 s. - Hard output bounds on every map verb. - Finding definitions: rank 1 in 103/140 cases versus 79/140 for `trail ask`. - Cheap no-op verification (0.04 to 1.34 s) versus `trail build --check` (2 to 86 s). - Structure for Markdown, JSON, TOML and YAML; large generated and minified files are still indexed. **Trail-Code wins** - Call graph: precise callers and callees with depth, recall 0.10 to 0.96, versus none in dctx. - Task answers: 122/140 versus 69/140 points; config lookup, concept search, impact and callees questions. - Text search (`trail grep`, grouped by enclosing symbol) and a bounded repository map (1 to 15k tokens). - Cache-friendly output: answers do not change when unrelated files change. - Incremental re-indexing; edits reach the graph without a full rebuild. - Language breadth (23 languages). - On the largest Rust corpus, warm `callers` and `skeleton` are faster than dctx (0.8 s versus 1.45 s) with less memory per query. **Ties** - Freshness correctness on unstaged, untracked, staged and reverted edits. - Neither follows symlink loops or escaping symlinks; both skip `node_modules/` and non-UTF-8 file names; neither crashed or hung on the adversarial corpus in its primary interface. - Both produce byte-identical text output for identical repeated queries. ## 16. Findings Each finding has an ID, severity, evidence and a recommendation that keeps dctx's philosophy: zero dependencies, a pure Rust core, no Git or network in the core, bounded outputs, privacy, and external effects only through consent-gated plugins. **TC-F01 (blocker): the shipped map CLI has no call or import edges.** Evidence: `neighbors --edge calls` empty for 140 of 140 targets across seven corpora (`data/accuracy.csv`); `--edge imports` empty on module ids in spot checks; Trail precision 0.94 to 1.00 and recall up to 0.96 on the same gold. In the task benchmark, dctx scored 7/14 on definition-and-callers questions, 7/14 on impact, 2/14 on callees and 6/14 on colliding names. The facade (`crates/dctx/src/index/extract.rs`) only emits `contains` edges, although the lexers already produce `Calls`/`Imports` references and `dctx-map-resolve` exists. Recommendation: wire reference facts from the lexers through `dctx-map-resolve` into the facade segment, with explicit confidence (`exact`, `name`, `guess`) on every edge and a record of dropped ambiguous targets. Start with same-file, same-module and imported-name resolution, which is enough for Trail's "rare" and "collision" recall (0.86 to 0.93). Gate any typed resolution behind the precision label instead of adding a type checker. Use `scripts/phase_accuracy.py` as the acceptance test. **TC-F02 (major): no incremental index, and generations grow without deduplication.** Evidence: the first query after a one-line edit costs about a full cold index (core 7.48 s versus 1.45 s warm; django 2.70 versus 0.82). The core cache grew from 158 MB to 946 MB after about five edits; three generations were byte-identical; `cache gc --dry-run` reclaimed 0 bytes (`unlink_grace`). Total cache at the end of the run: 1.36 GB. Recommendation: store per-file fact segments addressed by content hash and assemble generations from references, so an edit re-lexes one file and an unchanged snapshot reuses its predecessor. Reclaim superseded unpinned generations of the same root right away (or at the next run) instead of only after the grace and TTL windows. **TC-F03 (major): outputs are not prefix-stable or deterministic enough for prompt caching.** Evidence: every map answer starts with `# <place> <verb> v1:sha256:<digest>:<bytes> g=<n>`, so any edit anywhere changes byte 21 to 50 of every answer (`data/stability.csv`, 0 of 63 dctx answers unchanged after an unrelated edit versus 59 of 70 for Trail). JSON answers contain `freshness.age_s`, so no two JSON calls more than a second apart are identical. Recommendation: move snapshot identity and age to a trailer line or behind an opt-in flag; keep the first bytes of an answer a pure function of the answered nodes. Report age in coarse buckets or not at all in the default output. **TC-F04 (major): text mode is too thin for agents.** Evidence: `dctx map read <id>` and `explain <id>` in text mode print only the id line (152 to 247 bytes, no source, no signature); `find` text has no line numbers; JSON carries thirteen keys per record, often `null`, so a default-budget JSON `find` returned 4 records versus 10 in text. Recommendation: print source for `read` and the signature and summary for `explain` in text mode; add `path:start-end` to text records; drop `null` keys from JSON v2 (or add a compact JSON). **TC-F05 (major): no bounded repository overview.** Evidence: `dctx map map p:<place>` and `k:<dir>` answer `gone`, and directories are refused ("is a directory; pass a file path or a stable id"), although the guide says `map` outlines "the project root". The only overview is the legacy `dctx . -t`: 974 KB (278k tokens) on django, written into the repository as `.dctx/<place>.llmcontext.txt`, and it fails on trees deeper than 128. Trail's `map` answered in 1.7 to 53 KB. Recommendation: implement `map p:` and directory targets as a budgeted overview (directories, file counts, top symbols by in-degree once TC-F01 lands), paging through `next`, written to stdout only. **TC-F06 (major): no text search.** Evidence: config-key questions scored 0/14 for dctx and 14/14 for Trail (`trail grep`). Recommendation: add a bounded `dctx map grep` verb in the core (pure Rust, same ignore rules, no Git), grouped by enclosing symbol id and capped by `--budget` with a continuation cursor. **TC-F07 (major): large data files dominate cost.** Evidence: on core one 6.7 MB JSON fixture produced 235,842 symbols; the generation is 158 MB (2.9 times the tree); every warm query re-reads it (1.45 s, 370 MiB RSS). Trail answers the same corpus with a 65 MB index and 0.8 s queries. The adversarial corpus needed 262 MiB for its first query because of its 5 MB source files. Recommendation: cap configuration and data extraction per file (bytes or node count), mark capped files as `opaque` in the precision label, and load only the segment parts a query touches instead of the whole generation in every process. **TC-F08 (major, privacy): `dctx pack` emits `.env` contents by default.** Evidence: `dctx pack .` printed `DCTXBENCH_FAKE_SECRET=sk-test-...` from a non-gitignored `.env` (`data/raw/adversarial.jsonl`, both variants). Map answers and the map cache did not contain it. Trail never read `.env`. Recommendation: ship a default sensitive-content omit list (`.env*`, `*.pem`, `*.key`, `id_*`, `credentials*`, `*.p12`) that shows the path but never reads the content unless the user opts in. This matches the README's "never read" promise for secrets. **TC-F09 (minor): small budgets fail instead of degrading.** Evidence: `--budget 20` and JSON `--budget 100` exit 1 ("budget too small: needs at least 336 bytes"). Recommendation: return the largest prefix that fits (ids only, then `more`/`next`), or clamp to the floor and say so in the precision label. **TC-F10 (minor): concept search finds nothing for multi-word queries.** Evidence: all seven concept queries (multi-word, for example "wsgi app") returned an empty page (about 100 bytes, header only); Trail `ask` found the target in 6 of 7. Recommendation: split queries and identifiers on case and `_` boundaries, rank by token overlap with names and first-line doc summaries (already present as `summary`), all in the core without models. **TC-F11 (info): "Zero Dependencies" does not describe the built CLI.** Evidence: `cargo tree -p dctx-cli -e normal` lists 46 external crates, including `rusqlite` with bundled SQLite C, `ed25519-dalek`, `landlock`, `seccompiler`, `serde_json` and `syn` 3, all compiled into the release build (`target/release/deps`). The binary itself only needs libc, libm and libgcc_s at run time. Recommendation: either feature-gate the plugin, sandbox and store crates out of the default build, or change the badge and README to "no runtime dependencies" and list the audited crates. **TC-F12 (minor, docs): `docs/guides/MAP-MODE.md` and `--version --verbose` are stale.** Evidence: the guide says `.gitignore` rules are not loaded and `--lines` drops the start line; observed: gitignored files are excluded on the map path even without `.git`, and `--lines 240-246` returned exactly lines 240 to 246. The guide says `map` outlines the project root (it does not, TC-F05) and that the default CLI extracts "conservative calls" (none are exposed, TC-F01). `dctx --version --verbose` lists `languages: rust,javascript,typescript,markdown` and parser `dctx-lex-rust/syn-3.0.9`, while answers report `dctx-structural/1` and Python, Go and others work. Recommendation: regenerate the guide's limitation section and the verbose version block from tests. **TC-F13 (minor): silent omissions.** Evidence: files with a non-UTF-8 name or a newline in the name, and NUL-containing source files, were skipped without any signal in the answer or the precision label (Trail also skips non-UTF-8 names). Recommendation: count omitted paths by reason in `precision` (for example `omitted: {binary: 1, unnamed: 2}`) so an agent knows the map is incomplete. **TC-F14 (info): footprint, privacy and speed are real advantages; keep them.** Evidence: 9.2 MB binary versus 405.6 MB; 0 sockets versus a daily update check that ignores `DO_NOT_TRACK` and an install-time telemetry event; no repository writes versus `.gitignore`/`.ignore` edits on every Trail build; cold index 2.8 to 69 times faster on all seven corpora; definition ranking 103/140 versus 79/140. Recommendation: keep these as non-negotiable acceptance gates while closing TC-F01 to F07. **TC-F15 (info): do not copy Trail's in-band agent instructions.** Evidence: Trail prepends a ~310-byte banner to most answers that tells the agent to report "tokens saved" to the user (~89 tokens per call, 54% of `callees` output). It is prompt steering inside tool output and it changes when covered files change. Recommendation: keep dctx answers free of instructions; if savings metrics are useful, expose them in `dctx cache status` or a JSON field the caller can drop. **TC-F17 (info): Trail's freshness check costs a full build.** Evidence: `trail build --check` 49.5 s on pocketbase and 86.5 s on django, the same as cold builds; dctx verifies freshness on every query in 0.04 to 1.34 s. Recommendation: keep strict per-query verification as a dctx default and document it as a feature. **TC-F18 (info): Trail indexes gitignored files when `.git` is absent.** Evidence: in the no-git adversarial variant, Trail indexed `ignored_dir/` and `app.secret.py`; the fake secret value appeared in `graft/.cache/extract.*.json` and `trail grep` output. dctx excluded both. Recommendation: keep dctx's rule-based ignore handling independent of Git, and add this case to the dctx privacy test suite. ## 17. Not tested, and deviations - Trail `build --deep` (needs an LLM key) and `--lsp` (no language servers installed on the host); `trail blast`, `check`, `note`, `team`, `viz` and the learnings features; Trail cloud workspaces. - Callees and depth-2 accuracy were not adjudicated (latency, size and task facts only). - End-to-end agent outcomes (no model was run); exact tokenizer counts (estimator only). - Page-cache-cold timings (caches were not dropped on a shared host); other operating systems. - dctx plugins, TUI, templates and the optional `syntax-rust` build. - Deviation: `DO_NOT_TRACK` was not set during `npm install`, so Trail's `postinstall` recorded an install event and attempted a flush while the network was available. All later Trail runs had the opt-out set and ran without network. - Deviation: the network namespace does not block name resolution through systemd-resolved's varlink socket. Only the deliberate update-check audit (stamp removed) triggered a lookup; the stamp was restored before any other run, and runs with a fresh stamp made no socket calls. - Deviation: the flask freshness, bounding and coverage rows come from the validation run of the final scripts; the other corpora ran in one chained pass (`data/raw/phases.jsonl`). - dctx's overview row uses the legacy snapshot alias because the map verbs have no repository overview. ## 18. Reproducing 1. On a Linux host with passwordless sudo: `scripts/setup_host.sh` (user, workspace, dctx build, pinned Trail install, pinned clones). Copy `scripts/` to `$BENCH_ROOT/scripts`. 2. `scripts/run_all.sh` runs every phase. Each phase script appends JSONL under `$BENCH_ROOT/results`. 3. `python3 scripts/aggregate.py RESULTS data/` regenerates `data/*.csv` and `data/SUMMARY-TABLES.md`. For a private corpus, run `scripts/redact_private.py data/ <corpus>` before publishing. 4. Cleanup: `sudo userdel -r dctxbench && sudo rm -rf /path/to/workdir && sudo apt-get remove -y time strace`. All scripts are POSIX sh or Python 3 standard library only. ### Data index | Path | Content | |---|---| | `data/env.txt`, `data/tool-help.txt` | host, versions, pins, binary hash, `ldd`, CLI help of both tools | | `data/raw/runs.jsonl` and `*_runs.jsonl` | every measured command: wall, CPU, RSS, exit code, output bytes and sha256, load | | `data/raw/accuracy.jsonl`, `tasks.jsonl`, `freshness.jsonl`, `bounding.jsonl`, `coverage*.jsonl`, `adversarial.jsonl`, `network.jsonl`, `init_writes.jsonl`, `writes.jsonl`, `index_size.jsonl` | per-phase results | | `data/raw/strace.*.txt` | network audit traces | | `data/targets/` | targets, gold call sites and task questions per corpus (core reduced to counts) | | `data/outputs/` | first 16 KB of each raw answer (warm, unrelated-edit, accuracy and adversarial runs; core excluded) | | `data/*.csv`, `data/SUMMARY-TABLES.md` | aggregated tables | </FILE_CONTENT_END ID="F034"> ## Public HTML pages --- url: https://www.dctx.internet.technology/ title: dctx source: https://www.dctx.internet.technology/ --- dctx 1.3.1 Apache-2.0 C/Rust no telemetry not yet stable · pre-2.0 Give AI the right code, not all of it. dctx reads your project on your machine and hands an AI only the parts that matter, as one short page. Same project, same page, every time. No network, no telemetry. Under ~200 files, use grep. dctx pays off on large repos, multi-hop questions and many agents sharing one index. Choose your path Read the docs Playground GitHub Four ways to use it 1 Chat Paste a whole project into a chat One command turns a folder into one page you can paste into any AI chat. Secret files such as .env are listed by name and never read. Pack a project 2 Task Hand over only what a task needs Name the task in a few words and set a size limit. dctx picks the matching code, what calls it and its source, and stops at the limit. Pack for a task 3 Agent Let an agent explore a big repo The agent searches by name, gets short stable ids back, then reads only the piece it asks for. Same question, same answer, every turn. Map mode guide 4 Library Build it into your own tool Ask for --json and get structured records with the exact source. The Rust library works from Git today; Node is on npm as @tejl/dctx from 1.3.1; use CI artifacts for Python and Go. Embed the library Paste a whole project into a chat One command turns a folder into one page you can paste into any AI chat. Secret files such as .env are listed by name and never read. ~/kiosk · dctx 1.3.1 1/4 $ dctx pack . [DCTX_LLM_CONTEXT_SNAPSHOT_V1] [DIRECTORY:kiosk] … 9 lines <DIRECTORY_TREE > [D] (ID:ROOT) [F] .env (ID:F001) [F] .gitignore (ID:F002) … 13 lines <FILE_CONTENT_START ID = "F001" PATH = ".env" LINES = "0" > [Content omitted by pattern rules] </FILE_CONTENT_END ID = "F001" > … 156 more lines # exit 0 · 5,545 bytes · ~1,585 est. tokens Hand over only what a task needs Name the task in a few words and set a size limit. dctx picks the matching code, what calls it and its source, and stops at the limit. ~/kiosk · dctx 1.3.1 2/4 $ dctx pack . --for 'greet store' --budget 800 # dctx pack --for budget = 800 terms = 2 ## find greet s:src/util.rs#greet fn L2-4 s:web/app.ts#renderGreeting fn L10-12 … 10 lines ## read s:src/util.rs#greet s:src/util.rs#greet fn src/util.rs pub fn greet (name: & str ) -> String { format! ( "Hello, {}!" , title_case (name)) } … 7 lines # end body_tokens = 223 budget = 800 dropped = 0 # exit 0 · 822 bytes · ~235 est. tokens Let an agent explore a big repo The agent searches by name, gets short stable ids back, then reads only the piece it asks for. Same question, same answer, every turn. ~/kiosk · dctx 1.3.1 3/4 $ dctx map find greet # kiosk find s:src/util.rs#greet fn L2-4 s:web/app.ts#renderGreeting fn L10-12 # exit 0 · 79 bytes · ~23 est. tokens $ dctx map read 's:src/util.rs#greet' # kiosk read s:src/util.rs#greet fn src/util.rs pub fn greet (name: & str ) -> String { format! ( "Hello, {}!" , title_case (name)) } # exit 0 · 131 bytes · ~38 est. tokens Build it into your own tool Ask for --json and get structured records with the exact source. The Rust library works from Git today; Node is on npm as @tejl/dctx from 1.3.1; use CI artifacts for Python and Go. ~/kiosk · dctx 1.3.1 4/4 $ dctx map read 's:src/util.rs#greet' --json # one JSON line; pretty-printed here { "v" : 2 , "place" : "kiosk" , "verb" : "read" , … 9 lines "records" : [ { "id" : "s:src/util.rs#greet" , "kind" : "fn" , "path" : "src/util.rs" , … 11 lines "source_utf8" : "pub fn greet(name: &str) -> String {\n format!(\"Hello, {}!\", title_case(name))\n}" , … 8 lines } # exit 0 · 561 bytes · ~161 est. tokens Real commands and output, recorded from the dctx 1.3.1 binary on the kiosk sample project ; long output is cut where it says … Project status · in development since January 2026 Not yet stable. Working toward 2.0. dctx is not yet stable and not enterprise-ready . Until version 2.0, expect breaking changes often. January 2026 First commit 8 January 2026 1.3.1 · today 10 months in development at the 1.3.1 release; not yet stable denoising Breaking changes are expected often until 2.0 2.0 · stable Stability is the goal of version 2.0, and the project is working toward it. Why: AI providers keep changing how they optimize context on their side. dctx adapts to those changes quickly, but not in real time. Stability arrives with 2.0, and the project is working toward it. Where it comes from: dctx began as an internal tool that was never meant to be open-sourced, so parts of it are still messy. It was opened up because colleagues who rely on it needed it in the open, and development continues in public. We see an ultimate solution to this problem, and we are denoising it. Promise Zero dependencies The principle dctx was founded on. Today dctx still has dependencies. Goal The single best context management tool That is what dctx is being built to become. Why, where it comes from, and the goal Why: AI providers keep changing how they optimize context on their side. dctx adapts to those changes quickly, but not in real time. Stability arrives with 2.0, and the project is working toward it. Where it comes from: dctx began as an internal tool that was never meant to be open-sourced, so parts of it are still messy. It was opened up because colleagues who rely on it needed it in the open, and development continues in public. We see an ultimate solution to this problem, and we are denoising it. Promise Zero dependencies The principle dctx was founded on. Today dctx still has dependencies. Goal The single best context management tool That is what dctx is being built to become. Choose your path dctx fits into your work in a few different ways. Pick the situation that sounds most like yours: each path says what you get, what to set up, the first command to run and the one mistake to avoid. One giant folder Who it’s for You work inside one very large tree, for example a 200 GB monorepo, data or document folder. What you get Short answers about only the part of the tree you name; the rest is never scanned. What you use System binary, scoped roots, ignore rules at each root you query. Setup, first command and the pitfall Setup Install the system binary from GitHub Releases and verify it against SHA256SUMS. Write a .dctxignore at each root you will query: data, generated output and archives out ( .gitignore is read too). Decide which sub-roots a task can name: a package, a service, a document set. Optional: set fail-fast ceilings with DCTX_MAX_SOURCE_BYTES , DCTX_MAX_RECORDS and DCTX_MAX_ENTRIES . First command $ dctx map find Config --place packages/service-a --budget 500 --limit 5 Watch out for Pointing an agent at the whole root. Every call then has to scan or index far more than the task needs, and the cache cap can refuse it. Name the sub-root in the task, with --place or by starting in that folder. Open the full path -> Many smaller projects Who it’s for You move between many small and medium repositories during the day. What you get Install once, then run find and read from each project directory. What you use System binary, called directly from a shell or an agent's shell tool. Setup, first command and the pitfall Setup Install the system binary once and put it on PATH. Run the dctx CLI directly from your agent's shell tool. Start in the project directory, or use --place to name the project root. Nothing else per project: dctx reads .gitignore and .dctxignore where they already are. First command $ dctx map find NAME Watch out for Stale caches of projects you deleted or no longer use. Auto-clean runs once a day and drops unpinned roots after 30 idle days; to clean by hand, run dctx cache status , then dctx cache gc --dry-run or dctx cache purge --root PATH --dry-run . Open the full path -> Agent builder embedding a library Who it’s for You build an agent, editor or tool and want dctx inside it. What you get Stable ids and the exact source bytes inside your own app, from the same engine as the CLI. What you use Project library with its own pinned binary. Install the Node wrapper with npm install @tejl/dctx ; use CI artifacts for Python and Go, embed the Rust facade from a tagged Git dependency, or run a pinned CLI binary and read its --json output. Setup, first command and the pitfall Setup Pin one version in your project, for example the Rust facade: dctx = { git = "https://github.com/Eris-Margeta/dctx", tag = "v1.3.1" } . Pass your own ignore rules: the library does not load .gitignore by itself; the host supplies selection policy, storage limits and the clock. Move ids, not text: call find , keep the returned ids, call read with them. First command $ cargo test --locked -p dctx-library-example --doc Watch out for Re-implementing engine logic: parsing or slicing pack text, recounting budgets, rebuilding ids. Treat answers as opaque pages and stable ids; if you need a different shape, ask the engine for --json . Open the full path -> Team or organisation admin Who it’s for You roll dctx out to a team or a fleet of machines. What you get One verified, pinned version on every machine, with the same safety rules everywhere. What you use System binary distributed through your own package channel, one pinned version everywhere. Setup, first command and the pitfall Setup Download the release archives from GitHub Releases and verify them against SHA256SUMS and their cosign signatures; each release also ships an SBOM. Ship one pinned version through your own package manager, image or configuration tool. Ship shared ignore rules ( .dctxignore and a global ignore); the built-in deny for secrets, .git and symlinks always applies. Tighten the cache cap per machine if you need to: dctx cache config --max-bytes N can only lower it. First command $ dctx --version Watch out for Mixing project and system versions without checking. Run dctx doctor to list every binary in reach, and check dctx --version on PATH and the version each project pins, as part of onboarding. Open the full path -> Not sure? Take the safe path dctx is an advanced tool with several ways to use it. Used well, it cuts irrelevant text from selected tool answers. It does not save tokens by default; savings depend on a system reusing byte-identical, prefix-stable context. Extra calls can add tokens. If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything. Status: Receipts are planned. The safe path uses CLI commands from a shell or an agent's shell tool. Pause animation: the safe path Replay animation: the safe path Measure before you change anything. The safe path for a new user, with commands that exist in dctx 1.3.1. Receipts are planned. If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything. Step by step: A new user with one agent and one repository. Install the system binary: download the archive for your platform from GitHub Releases, check it with sha256sum -c SHA256SUMS --ignore-missing , then run dctx --version . Pick one project, not your home folder or a huge tree. The system binary serves it; nothing is installed per project. Run dctx map find NAME from the project root, then read a result with dctx read ID , using the shell or an agent's shell tool. Make the first call, for example dctx pack . --for 'greet store' --budget 800 , and read its last line: # end body_tokens=223 budget=800 dropped=0 on the sample project. Measure: per task, count the calls, the start-up tokens and the total input, and compare with grep and file reads on the same task. Receipts that count this for you are planned. Only then change one thing at a time. The safe path, the two scopes and every path in full -> What the output looks like # These are real runs on the tiny kiosk sample , captured by capture.py from the release binary. Commands run inside a copy named kiosk . For source builds, the executable is dctx-cli (or define a dctx alias). Pack a project # The header explains the format, the tree assigns IDs, and file blocks carry paths and line counts. The first 40 output lines follow; only the tail is omitted. .env is listed without its contents. $ dctx pack . [DCTX_LLM_CONTEXT_SNAPSHOT_V1] [DIRECTORY:kiosk] <INSTRUCTIONS > 1. Manifest: The <DIRECTORY_TREE > section lists all files. - Each entry: [TYPE] RELATIVE_PATH (ID:UNIQUE_ID) - TYPE is [D] for directory, [F] for file. 2. Content Access: To read a specific file: - Find its UNIQUE_ID from the directory tree. - Search for the marker: <FILE_CONTENT_START ID = "UNIQUE_ID" > - The content is between this marker and </FILE_CONTENT_END ID = "UNIQUE_ID" > </INSTRUCTIONS > <DIRECTORY_TREE > [D] (ID:ROOT) [F] .env (ID:F001) [F] .gitignore (ID:F002) [F] Cargo.toml (ID:F003) [F] README.md (ID:F004) [F] config.toml (ID:F005) [D] src (ID:D006) [F] src/main.rs (ID:F007) [F] src/store.rs (ID:F008) [F] src/util.rs (ID:F009) [D] tools (ID:D010) [F] tools/report.py (ID:F011) [D] web (ID:D012) [F] web/app.ts (ID:F013) [F] web/format.ts (ID:F014) </DIRECTORY_TREE > <FILE_CONTENT_START ID = "F001" PATH = ".env" LINES = "0" > [Content omitted by pattern rules] </FILE_CONTENT_END ID = "F001" > <FILE_CONTENT_START ID = "F002" PATH = ".gitignore" LINES = "2" > target / </FILE_CONTENT_END ID = "F002" > <FILE_CONTENT_START ID = "F003" PATH = "Cargo.toml" LINES = "9" > [package] name = "kiosk" version = "0.1.0" edition = "2021" … (147 more lines) Find a symbol, then read it # Pass the exact ID from find to read to get its metadata and verified source bytes: $ dctx map find greet # kiosk find s:src/util.rs#greet fn L 2 - 4 s:web/app.ts#renderGreeting fn L 10 - 12 $ dctx map read 's:src/util.rs#greet' # kiosk read s:src/util.rs#greet fn src/util.rs pub fn greet(name: &str) -> String { format!("Hello, {}!", title_case(name)) } For structured consumption, --json puts the same source bytes in source_utf8 (one JSON line, shown verbatim): $ dctx map read 's:src/util.rs#greet' --json { "v" : 2 , "place" : "kiosk" , "verb" : "read" , "freshness" :{ "mode" : "strict" , "state" : "verified" }, "precision" :{ "coverage" : "syntax" , "completion" : "complete" , "parser" : "dctx-lex-rust/syn-3.0.9" }, "records" :[{ "id" : "s:src/util.rs#greet" , "kind" : "fn" , "path" : "src/util.rs" , "lines" :[ 2 , 4 ], "summary" : "The greeting shown on the kiosk screen." , "summary_source" : "doc" , "signature" : null , "span" :[ 44 , 126 ], "source_utf8" : "pub fn greet(name: &str) -> String {\n format!(\"Hello, {}!\", title_case(name))\n}" , "edge" : null , "direction" : null , "target" : null , "confidence" : null }], "more" : 0 , "next" : null } Pack for a task # --for uses the task terms to select find results, neighbors and source reads. --budget 800 bounds estimated output tokens, not scan size; the footer reports usage and dropped records. $ dctx pack . --for 'greet store' --budget 800 # dctx pack --for budget = 800 terms = 2 ## find greet s:src/util.rs#greet fn L 2 - 4 s:web/app.ts#renderGreeting fn L 10 - 12 ## find store s:src/store.rs#Order struct L 4 - 8 s:src/store.rs#checksum fn L 22 - 24 s:src/store.rs#encode fn L 17 - 19 ## neighbors s:src/util.rs#greet calls:in:s:src/main.rs#main fn src/main.rs L 7 calls:out:s:src/util.rs#title_case fn src/util.rs contains:in:m:src/util.rs module src/util.rs ## neighbors s:src/store.rs#Order contains:in:m:src/store.rs module src/store.rs ## read s:src/util.rs#greet s:src/util.rs#greet fn src/util.rs pub fn greet(name: &str) -> String { format!("Hello, {}!", title_case(name)) } ## read s:src/store.rs#Order s:src/store.rs#Order struct src/store.rs pub struct Order { pub id: u 32 , pub item: String, pub qty: u 32 , } # end body_tokens = 223 budget = 800 dropped = 0 What has been measured Each number links to the document it is parsed from. grep + read the baseline for choosing a mode; count startup and every agent turn. Choosing how to use dctx 0.13–1.20 s cold index of 6 benchmark corpora, median of 3 runs. run 7 50 language families: 36 full, 8 outline, 6 docs. dctx languages 33/33 text and 33/33 JSON answers byte-identical after unrelated edits. report 0 socket attempts by dctx in every traced benchmark variant. network The baseline is grep plus reading files. The measured whole-session benchmark found a -5.01 % change in median total tokens with warm dctx CLI; the 25 % savings rule was not met. On this corpus and model dctx did not save 25 % tokens. The claim is accuracy and bounded context: CLI named more required files at about equal or higher token cost. dctx on its own does not save tokens by default. Savings come from a harness or agent system that reuses byte-identical, prefix-stable context across long sessions over a large body of work, with complete control over every byte. No measured savings figure exists for such a system yet. See the caching philosophy and both recall metrics, median and spread, and limitations . Returned bytes do not measure whole-session cost or establish an advantage over grep plus narrow line-range reads. Choose a mode and count startup context, all model turns and cached input. Evidence and secondary historical tables Pause animation: cost is calls times context Replay animation: cost is calls times context Calls cost more than output size. An illustration, not a measured result: every call re-reads the whole conversation so far. What the illustration shows (made-up units, not a benchmark): Each model call reads the whole conversation: the task and prompt, plus every earlier tool result. Agent A uses grep and file reads: eight calls with small results. The conversation grows a little with each call, and each call reads all of it again. Agent B uses dctx: two calls that return larger, bounded pages, then it is done. Adding up what every call re-reads (the shaded areas): 164 units for agent A, 29 for agent B. So the number of calls matters more than the size of one result. The reverse also holds: dctx used without a plan can add calls instead of removing them, so count the calls of your own sessions. Choosing how to use dctx explains how to count them. Ways to use it One binary, several modalities. Each has its own setup, cost and limits. CLI Pack a project or one task into a bounded page for chat, scripts and shell agents. available Agents, short session For a quick task grep plus a file read is often enough; add dctx only where a focused query saves turns. available Agents, long session Find, then read by stable id, with skeleton for orientation, in big files and long sessions. available ACP ACP is planned. planned Libraries Embed the engine in your own tool; the project pins its own binary and never re-implements engine logic. Rust from Git now; Python, Node and Go wrappers built in CI, Node on npm; Python and Go from CI CI and prompt cache Byte-stable output keeps the prompt prefix the same between runs, so provider caches can hit. available Pause animation: the giant folder Replay animation: the giant folder Index what the task touches, never copy the tree. The catalog and shards are the planned architecture. Today, point dctx at a sub-folder named in the task, not at the whole tree. What the animation shows (the planned architecture): A 200 GB folder: photos, datasets, archives and a folder of repositories. A catalog (planned) sweeps it once and records names and sizes only; no file contents are read. A task arrives: fix invoice rounding. Two shards match the task: repos/billing and repos/shared-ui . Only those two get symbol indexes; the rest of the tree is never indexed or copied. A bounded page, inside the budget and in a stable order, comes out of the two shards. What works today: start dctx on the sub-folder the task names (for example dctx map find invoice --place repos/billing ), with ignore rules for the rest. Who is responsible for what Each level of use has its own responsibilities. In full Items marked planned or pending are not in dctx 1.3.x yet. Level dctx provides You are responsible for System binary Release archives with SHA256SUMS, cache caps; signed binary, doctor, journals and receipts (planned) Choosing roots, the ignore rules (a policy file is planned), keeping one version on PATH Project library Pinned vendored binary, protocol client, same bytes as CLI (Node on npm; Python and Go from CI; Rust facade from Git) Pinning the version, exclusions in the project policy, not re-implementing engine logic ACP agent setup ACP planned Turning off the host's own file tools, picking a profile, session ids and reading receipts (both planned) CI and cache Byte-stable pack, deterministic exit codes; prefix tiers (planned) Pinning the binary, caching the index between runs, treating pack drift as a signal not noise Philosophy The binary is everything. One file holds the engine and the CLI; there is no service to run, no account and no model behind it. It works offline and makes zero network calls. The same tree and the same question give the same bytes, so answers can be compared, cached and trusted. Why dctx exists, in plain words . Pause animation: edit a file, keep the cache Replay animation: edit a file, keep the cache Edit a file, keep the cache. Illustrative sizes. The pack keeps a stable order and carries no timestamps by default, so a prompt cache can reuse every byte before the edit. What the animation shows: Turn 1: the pack is sent as one strip of bytes, file after file in a fixed order; the model provider caches it. You edit one file near the end of that order. Turn 2: the same tree gives the same bytes up to that file, so only the edited file and what follows are new. The cache reuses the unchanged prefix, here about three quarters of the bytes. If the pack began with a timestamp, the first byte would change and nothing would be reused. dctx answers carry no timestamps, digests or ages by default; --meta adds them back. Ordering rarely changed files first (prefix tiers) is planned. Ignored means never read Ignore rules first. .gitignore , .dctxignore and a global ignore exclude files before they are opened. README A built-in deny with no override. Env files, private keys, credential and secret files are listed by name but never read. README .git is closed. Never listed or read by the map verbs, never read by pack . README No symlink escapes. Files open with O_NOFOLLOW ; symlinked directories are never entered. README Local only. No telemetry, no model calls, no network for pack and map. README dctx decides by file name: a secret pasted into an ordinary source file is not detected. README Install Two scopes of the same binary: yours on PATH, and one pinned inside a project. System binary available now Download the archive for your OS from GitHub Releases, verify it against SHA256SUMS, extract it and put dctx on PATH. Archives cover Linux x64/ARM64, macOS x64/ARM64 and Windows x64. GitHub Releases (v1.3.1) README Quick start (README) Copy $ mkdir dctx-demo $ cd dctx-demo $ printf 'def hello(name):\n return f"Hello, {name}!"\n' > hello.py $ dctx map skeleton hello.py From source (Rust 1.91 or newer) Copy $ git clone https://github.com/Eris-Margeta/dctx $ cd dctx $ cargo build --locked --release -p dctx-cli $ ./target/release/dctx-cli --version $ alias dctx = "$PWD/target/release/dctx-cli" Project libraries Node on npm; Python and Go in CI Install the Node wrapper with npm install @tejl/dctx , then run npx @tejl/dctx . It pins the matching @tejl/dctx-<platform> optional dependency. Use CI artifacts for Python and Go, or embed the Rust facade from a tagged Git dependency. Cargo.toml (Rust facade, from Git today) Copy [dependencies] dctx = { git = "https://github.com/Eris-Margeta/dctx", tag = "v1.3.1" } Two scopes, one binary System binary: the dctx on PATH belongs to you and your agents, and you upgrade it. Interactive agents call this one. Project binary (Node from npm; Python and Go from CI): a binary installed by a project library lives inside that project (virtualenv, node_modules), pinned and managed by that package manager. Application code and CI call this one; a library never silently falls back to PATH. Same engine, different owner. dctx doctor lists every binary in reach; verify each against SHA256SUMS and its cosign signature. Compare modes, installs and status Pause animation: two scopes, one binary Replay animation: two scopes, one binary Same engine, different owner. The system dctx is yours; a project's dctx is pinned by that project. dctx doctor lists every dctx in reach; release archives are cosign-signed. What the animation shows, step by step: One machine. The system dctx on PATH (version 1.3.1) belongs to you and your agents; you decide when to upgrade it. A project vendors its own dctx inside node_modules or a virtualenv, pinned by its lockfile and upgraded only when the project bumps it. The Node wrapper is on npm as @tejl/dctx from 1.3.1; the pip package is built in CI, with registry publication pending. Both are the same engine at different versions. Interactive agents call the system binary; application code and CI call the project binary. A library never falls back to PATH silently. dctx doctor lists every dctx visible from the current folder with its version, build commit, scope and SHA-256. Verify prebuilt archives against SHA256SUMS and their cosign signatures. --- url: https://www.dctx.internet.technology/docs/ title: Documentation source: https://www.dctx.internet.technology/docs/ --- Documentation Documentation New here? Choose your path first: dctx is an advanced tool with several ways to use it. Evaluating dctx, or an AI doing so? Read the facts and how to verify them . Every document is rendered from the repository at build time, with a Markdown twin next to it ( index.md ), and all of them are in llms-full.txt . The CLI reference is generated from the binary: /cli/ . Start Document What it covers Words Updated Source Why dctx Why dctx exists, its philosophy, and why byte-identical output keeps the prompt cache hitting. 1,724 2026-11-13 docs/WHY-DCTX.md README Installation, quick start, map mode, language tiers and the CLI reference. 2,628 2026-11-17 README.md What dctx is The claim and its limits, the advanced-user notice, choose your path, the safe path in ten minutes, responsibilities and the two scopes. 1,655 2026-11-13 docs/START.md Modalities Document What it covers Words Updated Source Choosing how to use dctx Clipboard, grep plus reads, long sessions, huge trees, CLI usage and CI. 1,735 2026-11-13 docs/MODALITIES.md Map mode guide Every map verb with examples, budgets, ids and precision labels. 2,694 2026-11-13 docs/guides/MAP-MODE.md Agent snippet The AGENTS.md section that tells coding agents to ask dctx first. 196 2026-11-09 docs/guides/AGENTS-SNIPPET.md Plugins guide The plugin boundary, capabilities, consent and current limits. 980 2026-11-07 docs/guides/PLUGINS.md Engine Document What it covers Words Updated Source Specification The core belief, the five constraints, the ten RAG defect classes, policy and roadmap. 9,224 2026-11-13 docs/SPEC.md Privacy guarantees Ignore semantics and the full sensitive-file deny list. 2,817 2026-11-13 docs/ADR-014-Privacy-Guarantees-and-Ignore-Semantics.md Language coverage (ADR-018) The three tiers and how a language enters one. 516 2026-11-07 docs/ADR-018-Language-Coverage.md Template contract (DTS v2) DTS source v2 and the compiled plan IR v1. 648 2026-11-07 docs/design/contracts/DTS-v2.md Templating engine (ADR-003) Markers, ahead-of-time compilation, the two rendering passes and the data variables. 508 2026-11-07 docs/ADR-003-Templating-Engine.md Crate map How the Rust workspace is organised. 1,899 2026-11-07 docs/CRATE-MAP.md Reference Document What it covers Words Updated Source CLI exit codes The exit-code contract for map, pack and languages. 929 2026-11-13 docs/CLI-EXIT-CODES.md Trust Document What it covers Words Updated Source Measurement evidence Grep plus file reads first; whole-session scope and secondary historical protocols. 4,180 2026-11-13 docs/BENCHMARK-20261030.md Byte-stability report Protocol, raw answers and limits of the 33/33 measurement. 1,063 2026-11-07 docs/research/stability-20261105/REPORT.md Earlier two-way study October 2026, before call edges: the benchmark that set the roadmap. 7,229 2026-11-13 docs/research/trail-code-2026-10/REPORT.md Releasing How a release is cut and checked. 158 2026-11-07 RELEASING.md Contributing How to propose changes, with a DCO sign-off. 546 2026-11-13 CONTRIBUTING.md Policies Document What it covers Source Security policy How to report a vulnerability privately. SECURITY.md Trademark policy Use of the dctx name and logo. TRADEMARK.md Maintenance What a maintenance agreement covers. MAINTENANCE.md Crawlers, including AI crawlers, may read this site: see robots.txt and llms.txt . --- url: https://www.dctx.internet.technology/start/ title: Choose your path source: https://www.dctx.internet.technology/start/ --- Start Choose your path dctx fits into your work in a few different ways. Pick the situation that sounds most like yours: each path says what you get, what to set up, the first command to run and the one mistake to avoid. Four paths One giant folder Who it’s for You work inside one very large tree, for example a 200 GB monorepo, data or document folder. What you get Short answers about only the part of the tree you name; the rest is never scanned. What you use System binary, scoped roots, ignore rules at each root you query. Setup, first command and the pitfall Setup Install the system binary from GitHub Releases and verify it against SHA256SUMS. Write a .dctxignore at each root you will query: data, generated output and archives out ( .gitignore is read too). Decide which sub-roots a task can name: a package, a service, a document set. Optional: set fail-fast ceilings with DCTX_MAX_SOURCE_BYTES , DCTX_MAX_RECORDS and DCTX_MAX_ENTRIES . First command $ dctx map find Config --place packages/service-a --budget 500 --limit 5 Watch out for Pointing an agent at the whole root. Every call then has to scan or index far more than the task needs, and the cache cap can refuse it. Name the sub-root in the task, with --place or by starting in that folder. Open the full path -> Many smaller projects Who it’s for You move between many small and medium repositories during the day. What you get Install once, then run find and read from each project directory. What you use System binary, called directly from a shell or an agent's shell tool. Setup, first command and the pitfall Setup Install the system binary once and put it on PATH. Run the dctx CLI directly from your agent's shell tool. Start in the project directory, or use --place to name the project root. Nothing else per project: dctx reads .gitignore and .dctxignore where they already are. First command $ dctx map find NAME Watch out for Stale caches of projects you deleted or no longer use. Auto-clean runs once a day and drops unpinned roots after 30 idle days; to clean by hand, run dctx cache status , then dctx cache gc --dry-run or dctx cache purge --root PATH --dry-run . Open the full path -> Agent builder embedding a library Who it’s for You build an agent, editor or tool and want dctx inside it. What you get Stable ids and the exact source bytes inside your own app, from the same engine as the CLI. What you use Project library with its own pinned binary. Install the Node wrapper with npm install @tejl/dctx ; use CI artifacts for Python and Go, embed the Rust facade from a tagged Git dependency, or run a pinned CLI binary and read its --json output. Setup, first command and the pitfall Setup Pin one version in your project, for example the Rust facade: dctx = { git = "https://github.com/Eris-Margeta/dctx", tag = "v1.3.1" } . Pass your own ignore rules: the library does not load .gitignore by itself; the host supplies selection policy, storage limits and the clock. Move ids, not text: call find , keep the returned ids, call read with them. First command $ cargo test --locked -p dctx-library-example --doc Watch out for Re-implementing engine logic: parsing or slicing pack text, recounting budgets, rebuilding ids. Treat answers as opaque pages and stable ids; if you need a different shape, ask the engine for --json . Open the full path -> Team or organisation admin Who it’s for You roll dctx out to a team or a fleet of machines. What you get One verified, pinned version on every machine, with the same safety rules everywhere. What you use System binary distributed through your own package channel, one pinned version everywhere. Setup, first command and the pitfall Setup Download the release archives from GitHub Releases and verify them against SHA256SUMS and their cosign signatures; each release also ships an SBOM. Ship one pinned version through your own package manager, image or configuration tool. Ship shared ignore rules ( .dctxignore and a global ignore); the built-in deny for secrets, .git and symlinks always applies. Tighten the cache cap per machine if you need to: dctx cache config --max-bytes N can only lower it. First command $ dctx --version Watch out for Mixing project and system versions without checking. Run dctx doctor to list every binary in reach, and check dctx --version on PATH and the version each project pins, as part of onboarding. Open the full path -> Advanced tool, several ways to use it dctx is an advanced tool with several ways to use it. Used well, it cuts irrelevant text from selected tool answers. It does not save tokens by default; savings depend on a system reusing byte-identical, prefix-stable context. Extra calls can add tokens. If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything. Status: Receipts are planned. The safe path uses CLI commands from a shell or an agent's shell tool. dctx one binary, local and offline CLI pack $ dctx pack . Pack a project or one task into a bounded page for chat, scripts and shell agents. available Map mode for agents $ dctx map find greet Find, then read by stable id, with skeleton for orientation, in big files and long sessions. available Library and wrappers Rust · Python · Node · Go Embed the engine in your own tool; the project pins its own binary and never re-implements engine logic. Rust from Git now; Python, Node and Go wrappers built in CI, Node on npm; Python and Go from CI The safe path, if you are not sure One project. Start with one project you know, not your whole disk. The system binary. Install the release archive from GitHub Releases and verify it against SHA256SUMS. Direct CLI commands. Run dctx map find NAME , then dctx read ID , from the project root. Measure. Run the same task with grep plus file reads and with dctx; compare whole-session tokens and calls, not only answer size. Then pick the path above that matches your work. Choosing how to use dctx compares every mode with grep plus file reads. Two scopes, one binary System binary: the dctx on PATH belongs to you and your agents, and you upgrade it. Interactive agents call this one. Project binary (Node from npm; Python and Go from CI): a binary installed by a project library lives inside that project (virtualenv, node_modules), pinned and managed by that package manager. Application code and CI call this one; a library never silently falls back to PATH. Same engine, different owner. dctx doctor lists every binary in reach; verify each against SHA256SUMS and its cosign signature. Who is responsible for what Each level of use has its own responsibilities. dctx provides the left column; the right column is yours. Items marked planned or pending are not in dctx 1.3.x yet. Level dctx provides You are responsible for System binary Release archives with SHA256SUMS, cache caps; signed binary, doctor, journals and receipts (planned) Choosing roots, the ignore rules (a policy file is planned), keeping one version on PATH Project library Pinned vendored binary, protocol client, same bytes as CLI (Node on npm; Python and Go from CI; Rust facade from Git) Pinning the version, exclusions in the project policy, not re-implementing engine logic ACP agent setup ACP planned Turning off the host's own file tools, picking a profile, session ids and reading receipts (both planned) CI and cache Byte-stable pack, deterministic exit codes; prefix tiers (planned) Pinning the binary, caching the index between runs, treating pack drift as a signal not noise --- url: https://www.dctx.internet.technology/start/giant-folder/ title: One giant folder source: https://www.dctx.internet.technology/start/giant-folder/ --- Choose your path One giant folder You work inside one very large tree, for example a 200 GB monorepo, data or document folder. you get Short answers about only the part of the tree you name; the rest is never scanned. modality System binary, scoped roots, ignore rules at each root you query. version dctx 1.3.1 Setup Install the system binary from GitHub Releases and verify it against SHA256SUMS. Write a .dctxignore at each root you will query: data, generated output and archives out ( .gitignore is read too). Decide which sub-roots a task can name: a package, a service, a document set. Optional: set fail-fast ceilings with DCTX_MAX_SOURCE_BYTES , DCTX_MAX_RECORDS and DCTX_MAX_ENTRIES . First command shell Copy $ dctx map find Config --place packages/service-a --budget 500 --limit 5 What to expect A bounded page that starts with a # <place> find header and lists one stable id per line. Only the named sub-root is scanned and indexed; dctx cache status --json shows what the cache holds, under a 2 GiB hard cap. A scan over a limit fails with an error instead of returning a partial index. A real run on the kiosk sample project , recorded from the release binary by capture.py : ~/kiosk · dctx 1.3.1 $ dctx map find greet # kiosk find s:src/util.rs#greet fn L2-4 s:web/app.ts#renderGreeting fn L10-12 # exit 0 · 79 bytes · ~23 est. tokens The pitfall Pointing an agent at the whole root. Every call then has to scan or index far more than the task needs, and the cache cap can refuse it. Name the sub-root in the task, with --place or by starting in that folder. Read next Huge trees: scope before indexing · Map mode guide · Who is responsible for what Other paths: Many smaller projects Agent builder embedding a library Team or organisation admin dctx is an advanced tool with several ways to use it. Used well, it cuts irrelevant text from selected tool answers. It does not save tokens by default; savings depend on a system reusing byte-identical, prefix-stable context. Extra calls can add tokens. If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything. Status: Receipts are planned. The safe path uses CLI commands from a shell or an agent's shell tool. --- url: https://www.dctx.internet.technology/start/many-projects/ title: Many smaller projects source: https://www.dctx.internet.technology/start/many-projects/ --- Choose your path Many smaller projects You move between many small and medium repositories during the day. you get Install once, then run find and read from each project directory. modality System binary, called directly from a shell or an agent's shell tool. version dctx 1.3.1 Setup Install the system binary once and put it on PATH. Run the dctx CLI directly from your agent's shell tool. Start in the project directory, or use --place to name the project root. Nothing else per project: dctx reads .gitignore and .dctxignore where they already are. First command shell Copy $ dctx map find NAME What to expect find returns stable ids; read returns the verified source bytes of one id. The captured run below shows find on the sample project. A real run on the kiosk sample project , recorded from the release binary by capture.py : ~/kiosk · dctx 1.3.1 $ dctx map find greet # kiosk find s:src/util.rs#greet fn L2-4 s:web/app.ts#renderGreeting fn L10-12 # exit 0 · 79 bytes · ~23 est. tokens The pitfall Stale caches of projects you deleted or no longer use. Auto-clean runs once a day and drops unpinned roots after 30 idle days; to clean by hand, run dctx cache status , then dctx cache gc --dry-run or dctx cache purge --root PATH --dry-run . Read next Choosing how to use dctx · Who is responsible for what Other paths: One giant folder Agent builder embedding a library Team or organisation admin dctx is an advanced tool with several ways to use it. Used well, it cuts irrelevant text from selected tool answers. It does not save tokens by default; savings depend on a system reusing byte-identical, prefix-stable context. Extra calls can add tokens. If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything. Status: Receipts are planned. The safe path uses CLI commands from a shell or an agent's shell tool. --- url: https://www.dctx.internet.technology/start/library/ title: Agent builder embedding a library source: https://www.dctx.internet.technology/start/library/ --- Choose your path Agent builder embedding a library You build an agent, editor or tool and want dctx inside it. you get Stable ids and the exact source bytes inside your own app, from the same engine as the CLI. modality Project library with its own pinned binary. Install the Node wrapper with npm install @tejl/dctx ; use CI artifacts for Python and Go, embed the Rust facade from a tagged Git dependency, or run a pinned CLI binary and read its --json output. version dctx 1.3.1 Setup Pin one version in your project, for example the Rust facade: dctx = { git = "https://github.com/Eris-Margeta/dctx", tag = "v1.3.1" } . Pass your own ignore rules: the library does not load .gitignore by itself; the host supplies selection policy, storage limits and the clock. Move ids, not text: call find , keep the returned ids, call read with them. First command shell Copy $ cargo test --locked -p dctx-library-example --doc What to expect The ten-line library example compiles and runs against an in-memory source. With the CLI, --json answers carry the same records, and read puts the exact source in source_utf8 . A real run on the kiosk sample project , recorded from the release binary by capture.py : ~/kiosk · dctx 1.3.1 $ dctx map read 's:src/util.rs#greet' --json { "v" : 2 , "place" : "kiosk" , "verb" : "read" , "freshness" : { "mode" : "strict" , "state" : "verified" }, "precision" : { "coverage" : "syntax" , "completion" : "complete" , "parser" : "dctx-lex-rust/syn-3.0.9" }, "records" : [ { "id" : "s:src/util.rs#greet" , "kind" : "fn" , "path" : "src/util.rs" , "lines" : [ 2 , 4 ], "summary" : "The greeting shown on the kiosk screen." , "summary_source" : "doc" , "signature" : null , "span" : [ 44 , 126 ], "source_utf8" : "pub fn greet(name: &str) -> String {\n format!(\"Hello, {}!\", title_case(name))\n}" , "edge" : null , "direction" : null , "target" : null , "confidence" : null } ], "more" : 0 , "next" : null } # exit 0 · 561 bytes · ~161 est. tokens The pitfall Re-implementing engine logic: parsing or slicing pack text, recounting budgets, rebuilding ids. Treat answers as opaque pages and stable ids; if you need a different shape, ask the engine for --json . Read next Rust library: embed the facade · Use as a library · Who is responsible for what Other paths: One giant folder Many smaller projects Team or organisation admin dctx is an advanced tool with several ways to use it. Used well, it cuts irrelevant text from selected tool answers. It does not save tokens by default; savings depend on a system reusing byte-identical, prefix-stable context. Extra calls can add tokens. If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything. Status: Receipts are planned. The safe path uses CLI commands from a shell or an agent's shell tool. --- url: https://www.dctx.internet.technology/start/team/ title: Team or organisation admin source: https://www.dctx.internet.technology/start/team/ --- Choose your path Team or organisation admin You roll dctx out to a team or a fleet of machines. you get One verified, pinned version on every machine, with the same safety rules everywhere. modality System binary distributed through your own package channel, one pinned version everywhere. version dctx 1.3.1 Setup Download the release archives from GitHub Releases and verify them against SHA256SUMS and their cosign signatures; each release also ships an SBOM. Ship one pinned version through your own package manager, image or configuration tool. Ship shared ignore rules ( .dctxignore and a global ignore); the built-in deny for secrets, .git and symlinks always applies. Tighten the cache cap per machine if you need to: dctx cache config --max-bytes N can only lower it. First command shell Copy $ dctx --version What to expect One line with the version on every machine; dctx --version --verbose adds the feature list and precision and cache limits. Every machine should print the same line. A real run on the kiosk sample project , recorded from the release binary by capture.py : ~/kiosk · dctx 1.3.1 $ dctx --version dctx 1.3.1 (<git sha>) # exit 0 · 23 bytes · ~7 est. tokens The pitfall Mixing project and system versions without checking. Run dctx doctor to list every binary in reach, and check dctx --version on PATH and the version each project pins, as part of onboarding. Read next Privacy guarantees · Security policy · Who is responsible for what Other paths: One giant folder Many smaller projects Agent builder embedding a library dctx is an advanced tool with several ways to use it. Used well, it cuts irrelevant text from selected tool answers. It does not save tokens by default; savings depend on a system reusing byte-identical, prefix-stable context. Extra calls can add tokens. If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything. Status: Receipts are planned. The safe path uses CLI commands from a shell or an agent's shell tool. --- url: https://www.dctx.internet.technology/for-ai-evaluators/ title: For AI evaluators source: https://www.dctx.internet.technology/for-ai-evaluators/ --- For AI evaluators Facts and how to verify them For people and models deciding what dctx is. Every line below comes from one file, tools/website/data/facts.json , plus the benchmark documents; llms-small.txt , llms.txt and llms-full.txt start with the same facts. What dctx is, and is not dctx is an open-source (Apache-2.0) Rust context engine for AI-assisted coding: one local binary that packs a project into one structured block, or answers bounded, byte-stable symbol queries (find, read, neighbors, skeleton) as CLI output. No RAG: no embeddings, no vector search, and the engine never calls a model. No network: pack, map and cache make no network calls; the release check counts socket calls under strace and fails on any. No telemetry, not even opt-out. No agent loop: dctx answers one command at a time; the agent or the human decides what to ask next. Current version dctx 1.3.1 , released 2026-11-09 (tag v1.3.1 ), Apache-2.0. Release on GitHub · Changelog Each release on GitHub ships prebuilt archives for Linux x64/ARM64, macOS x64/ARM64 and Windows x64 with a SHA256SUMS file. Verify a download with sha256sum --check --ignore-missing SHA256SUMS . Releases from 1.3.0 also ship keyless cosign signatures, CycloneDX SBOMs, build provenance and offline bundles; see [verification](https://github.com/Eris-Margeta/dctx/blob/main/docs/VERIFYING.md). Modalities CLI available : dctx pack PATH for one structured block (clipboard, file or stdout); dctx map find|read|neighbors|skeleton|... for bounded symbol answers. Task context available : dctx pack --for TEXT --budget N : find, neighbors and read of the names in TEXT, cut to an estimated-token budget. CI and prompt cache available : Deterministic pack and map output; tree lines carry no timestamps by default, so the prefix stays stable across a touch. Rust library available from Git : The dctx facade crate as a tagged Git dependency; crates.io publication pending. Desktop app preview : A Tauri preview you build from source; a GPUI rebuild is planned. Python, Node and Go wrappers Node on npm; Python and Go from CI : Thin dctx rpc wrappers, built and tested in CI. Install Node with npm install @tejl/dctx , which includes pinned @tejl/dctx-<platform> optional dependencies; use CI artifacts for Python and Go. Two scopes, one binary System binary: the dctx on PATH belongs to you and your agents, and you upgrade it. Interactive agents call this one. Project binary (Node from npm; Python and Go from CI): a binary installed by a project library lives inside that project (virtualenv, node_modules), pinned and managed by that package manager. Application code and CI call this one; a library never silently falls back to PATH. Same engine, different owner. dctx doctor lists every binary in reach; verify each against SHA256SUMS and its cosign signature. The notice This is the canonical wording, from What dctx is ( docs/START.md ) and the README; the home page and Choose your path carry it verbatim: dctx is an advanced tool with several ways to use it. Used well, it cuts irrelevant text from selected tool answers. It does not save tokens by default; savings depend on a system reusing byte-identical, prefix-stable context. Extra calls can add tokens. If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything. Status: Receipts are planned. The safe path uses CLI commands from a shell or an agent's shell tool. Responsibilities Items marked planned or pending are not in dctx 1.3.x yet. Level dctx provides You are responsible for System binary Release archives with SHA256SUMS, cache caps; signed binary, doctor, journals and receipts (planned) Choosing roots, the ignore rules (a policy file is planned), keeping one version on PATH Project library Pinned vendored binary, protocol client, same bytes as CLI (Node on npm; Python and Go from CI; Rust facade from Git) Pinning the version, exclusions in the project policy, not re-implementing engine logic ACP agent setup ACP planned Turning off the host's own file tools, picking a profile, session ids and reading receipts (both planned) CI and cache Byte-stable pack, deterministic exit codes; prefix tiers (planned) Pinning the binary, caching the index between runs, treating pack drift as a signal not noise Benchmark status Baseline: grep plus reading files . measured 11 November 2026: 20 questions, a private 13-crate Rust workspace, claude-sonnet-5-5, dctx 1.3.0, three repeats per arm. Median total tokens [min, max]: grep plus reads 14,904,014 [14,604,149, 15,622,381]; dctx CLI (warm index) 14,157,974 [11,221,908, 15,613,375]. CLI median tokens were -5.01 % versus grep. On this corpus and model dctx did not save 25 % tokens; the pre-registered rule was not met. Official strict citation recall medians [min, max]: grep 10.10 % [10.10, 20.73]; CLI 14.46 % [8.36, 22.65]. Diagnostic file-level recall medians: 53.77 % and 71.70 %, respectively; diagnostic, not a replacement metric. The claim is accuracy and bounded context, not token savings. dctx on its own does not save tokens by default. Savings depend on a harness or agent system reusing byte-identical, prefix-stable context across long sessions; there is no measured, citable savings figure for such a system yet. One corpus, one model, no significance claim; corpus and raw answers private and cannot be published; dctx 1.3.0 is not current HEAD. Under ~200 files, use grep. Source measured Byte stability: the same query on unchanged code returns the same bytes; 33 of 33 text and JSON answers were byte-identical after unrelated edits (Linux only). Source historical The October and November in-house numbers (run 7: 140 of 140 task questions, cold index and warm latency) measure tool output only, as estimated stdout tokens and raw fact coverage without a model; they are not agent completion rates or session costs. Source hypothesis That a pack template changes model answer quality or cost is a hypothesis pending an A/B test; nothing on this site measures it. Source Measured values, as the documents state them today: Parsed from the documents at build time; nothing is retyped. Value What it measures Source 33/33 text, 33/33 JSON map answers byte-identical after unrelated edits and over five runs, three Linux corpora docs/research/stability-20261105/REPORT.md 0 socket attempts by dctx in every traced benchmark variant docs/BENCHMARK-20261030.md 0.13-1.20 s cold index of 6 benchmark corpora, median of 3 runs docs/research/bench-3way-20261030/results/run7-53f8b6b/aggregate.json 50 language families: 36 full, 8 outline, 6 docs dctx languages Removed in 1.2.0 These existed before 1.2.0 and no longer work. A transcript that uses them describes an old version. No longer exists Use instead dctx PATH (the implicit snapshot command, for example dctx . ) dctx pack PATH the top-level snapshot flags -d / --diff , -t / --tree and -r / --reset dctx pack PATH with its filters the project rule files .legacyignore and .dctxomitcontent .gitignore and .dctxignore dctx cache gc --legacy and its export-selection flags dctx cache gc How to verify a claim Claim How to check it Test suite cargo test --workspace --locked --exclude dctx-desktop --exclude dctx-desktop-api CI Every push and pull request runs the suite on Linux, macOS (ARM64 and x64) and Windows, on stable Rust and the minimum supported version 1.91. No network calls scripts/release-check.sh --quick target/release/dctx-cli Byte stability python3 docs/research/stability-20261105/verify.py Historical benchmark docs/research/bench-3way-20261030/run-3way.sh target/release/dctx-cli Every output on this site Recorded from the real binary by tools/website/capture.py; tools/website/check.py re-records and fails on drift. --- url: https://www.dctx.internet.technology/why/ title: Why dctx source: https://github.com/Eris-Margeta/dctx/blob/main/docs/WHY-DCTX.md --- Document: `docs/WHY-DCTX.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/why/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt Why dctx exists View source · Edit on GitHub · Markdown · docs/WHY-DCTX.md · 1,724 words · updated 13 November 2026 On this page The problem What dctx does The philosophy Why byte-identical output matters What dctx is not Where to go next Sources in this repository The problem # An AI coding assistant only knows what is in its context window : the text sent to the model with your request. It cannot see the rest of your project. Each of these costs you. Models read text as tokens (small chunks of text, roughly a short word or part of one), and providers bill per token. The model reads every token before it answers, so more tokens also means more waiting. And answers get worse as irrelevant text piles up. The README sums it up: every token in front of a model is paid for three times, to read it, again when a cache is missed, and again in attention. What dctx does # Start with grep plus file reads # surface that fits in Choosing how to use dctx . A small worked example # Run with dctx 1.1.0 on a copy of this repository's crates/dctx-lex-go folder. The output is real and complete. s:tests/fixtures/basic.go#Add fn L 43 - 45 calls:in:s:tests/fixtures/basic.go#main fn tests/fixtures/basic.go L 59 find returns a stable id, the kind of thing it is (a function) and its lines. This is a historical 1.1.0 transcript; the current CLI also includes verified source bytes in text read output, or in source_utf8 with read --json . neighbors says that main calls it, on line 59. The philosophy # The specification turns this into five testable rules. Bounded. Every map answer has a size ceiling, reserved before anything is written, and a record is never split. The budget is up to 2,000 estimated tokens (1,000 for explain ). Why it matters to you: one question cannot flood the context window and crowd out your own instructions. Deterministic. The same code and the same question give the same bytes. Why it matters to you: results are repeatable, and repeated prompts can be served from a cache. Prefix-stable. When context is sent again across turns, bytes that did not need to change do not change. Why it matters to you: this is what keeps caching working across a conversation. Non-redundant. Within one session, do not resend what was already sent unless it changed. This one is still a target. Honest. Every answer states its freshness, precision and provenance, and dctx never asserts what it does not know. With --json , the read above carries "freshness":{"mode":"strict","state":"verified"} , a precision block, and more and next fields for anything that did not fit. Calls it cannot resolve are listed as unresolved , not guessed. Why it matters to you: you and your assistant can tell a fact from a guess. Offline. No telemetry, no update checks, no model calls. A release check counted zero network connections across 16 commands. Nothing leaves your machine. Private by default. A file is classified before any byte of it is read. Secret-shaped files such as .env , *.pem and id_rsa are listed with content omitted, with no override in v1. No embeddings. dctx does not turn code into vectors and search by similarity. It ranks by names and syntax. Features must earn their place. A feature without a measured acceptance gate is not a dctx feature. Prompt caching, in plain words # Much of each request to an AI model repeats the last one: system instructions, project context, earlier turns. Providers keep a cache of prompt beginnings. If the start of a new prompt matches a cached one exactly, byte for byte, they reuse their earlier work on that part. Cached input costs a fraction of the normal price and is processed faster. Prefix-stable, simply # Timestamps are the classic problem. In 1.0.0, every line of the dctx pack file tree carried a modification time, and file lines a size. The tree sits near the top, so merely re-saving a file (a touch ) changed almost the whole page as far as a cache is concerned. Since 1.1.0 tree lines carry only an id. A bare touch leaves the output byte-identical, and an edit keeps everything before the edited file as a shared prefix. --tree-stamps=on brings back the old lines. In the same folder we appended one comment line to the last file in the tree, tests/review_lexers_a.rs , and compared dctx pack . before and after: The evidence # The stability report measured map answers on 6 November 2026, on three pinned local corpora with 11 kinds of question each. 33 of 33 text answers and 33 of 33 JSON answers were byte-identical after an unrelated edit elsewhere in the project, and all were identical over five separate runs. The report states its limits too. It measures dctx's answers, not a provider's cache hits. It ran on Linux only. The layered design that would keep context prefix-stable across a whole conversation ( SPEC §12.1 ) is still a target. Savings belong to the system # 11 November benchmark , the dctx CLI arm used 5.01 % fewer An illustration of money and time # Made-up numbers, not any provider's prices. Assume: Other reasons determinism matters # Reproducible reviews. A colleague who runs the same command on the same code sees exactly what the assistant saw. Meaningful diffs. If saved context changes, the code changed, not a clock or a sort order. Trust. A tool whose answers shift for no reason is hard to rely on. In the spec's words, "trust is the product". What dctx is not # Not a type checker. Call edges come from names, scopes and imports; ambiguous references are dropped. Not exact token counting. Budgets use an estimate, ceil(2 × UTF-8 bytes / 7) , not a model's tokenizer. Not vector search or RAG. No embeddings in the core, and the engine never calls a model. Not a hosted service or a daemon. One binary that runs when you call it. No telemetry, not even opt-out. Limits still matter. Plain dctx pack sends the selected project without an output budget by default. A 100 GB tree needs scoping, and the cache has a 2 GiB hard cap. CI covers Linux, macOS and Windows; byte-stability measurements here ran on Linux only. Where to go next # README : install, quick start, map mode. Specification : rules, metrics, roadmap. Measurement evidence : grep plus file reads first; other-tool numbers are secondary historical notes. Stability report : protocol, raw answers and limits. Map mode guide : every verb and option. Sources in this repository # README.md : core belief, map-mode budgets, pack tree lines, --tree-stamps , tested platform. CHANGELOG.md : 1.1.0 prefix-stable pack output, stability re-measurement. docs/SPEC.md : §2 rules PPE-1 to PPE-5, §3 defects R1 and R7, §4 privacy and no network, §11 page formats, §12.1 tiers, §13 token estimate, §32 non-goals. docs/research/stability-20261105/REPORT.md : 33/33 results and limits. docs/BENCHMARK-20261030.md : unresolved call records. Worked example and prefix figures: output of dctx 1.1.0 ( a4f6378 , built from crates/dctx-cli ) on a copy of crates/dctx-lex-go . --- url: https://www.dctx.internet.technology/docs/readme/ title: README source: https://github.com/Eris-Margeta/dctx/blob/main/README.md --- Document: `README.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/readme/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt dctx View source · Edit on GitHub · Markdown · README.md · 2,628 words · updated 17 November 2026 On this page Project status Installation What the output looks like Which mode? Measured, in the open Start and choose your path The core belief: prompt-processing efficiency Quick Start Map mode: context for agents From source Use as a library Versioned pack JSON CLI Reference Security & Privacy Open source and maintenance Where it comes from Contributing dctx turns any folder into the smallest correct context for a task, offline, with byte-stable output that prompt caches can reuse. dctx is an advanced tool with several ways to use it. Used well, it cuts irrelevant text from selected tool answers. It does not save tokens by default; savings depend on a system reusing byte-identical, prefix-stable context. Extra calls can add tokens. If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything. Run dctx agent-setup --format agents (or --format claude ) for short rules to paste into AGENTS.md or CLAUDE.md . Project status # dctx is not yet stable and not enterprise-ready. It has been in development since January 2026. Until version 2.0, expect breaking changes often. AI providers keep changing how they optimize context on their side; dctx adapts to those changes quickly, but not in real time. Stability is the goal of 2.0, and the project is working toward it: we see an ultimate solution to this problem, and we are denoising it. Installation # System binary — available now. Download the archive for your OS and architecture from GitHub Releases , compare its SHA-256 with the matching entry in SHA256SUMS , extract it, and put dctx ( dctx.exe on Windows) on PATH . Archives cover Linux x64/ARM64, verification, provenance and offline installation . Node wrapper — available on npm from 1.3.1. Run npm install @tejl/dctx to install the Node wrapper and its matching pinned @tejl/dctx-<platform> native package, then npx @tejl/dctx --version to check it. The Python and Go wrappers over dctx rpc are built and tested in CI; use their CI artifacts. The Rust facade is available from Follow the safe path in ten minutes What the output looks like # These are real runs on the tiny kiosk sample , captured by capture.py from the release binary. Commands run inside a copy named kiosk . For source builds, the executable is dctx-cli (or define a dctx alias). Pack a project # The header explains the format, the tree assigns IDs, and file blocks carry paths and line counts. The first 40 output lines follow; only the tail is omitted. .env is listed without its contents. <INSTRUCTIONS > 1. Manifest: The <DIRECTORY_TREE > section lists all files. - Search for the marker: <FILE_CONTENT_START ID = "UNIQUE_ID" > - The content is between this marker and </FILE_CONTENT_END ID = "UNIQUE_ID" > </INSTRUCTIONS > <DIRECTORY_TREE > </DIRECTORY_TREE > <FILE_CONTENT_START ID = "F001" PATH = ".env" LINES = "0" > </FILE_CONTENT_END ID = "F001" > <FILE_CONTENT_START ID = "F002" PATH = ".gitignore" LINES = "2" > target / </FILE_CONTENT_END ID = "F002" > <FILE_CONTENT_START ID = "F003" PATH = "Cargo.toml" LINES = "9" > Find a symbol, then read it # Pass the exact ID from find to read to get its metadata and verified source bytes: s:src/util.rs#greet fn L 2 - 4 s:web/app.ts#renderGreeting fn L 10 - 12 For structured consumption, --json puts the same source bytes in source_utf8 (one JSON line, shown verbatim): { "v" : 2 , "place" : "kiosk" , "verb" : "read" , "freshness" :{ "mode" : "strict" , "state" : "verified" }, "precision" :{ "coverage" : "syntax" , "completion" : "complete" , "parser" : "dctx-lex-rust/syn-3.0.9" }, "records" :[{ "id" : "s:src/util.rs#greet" , "kind" : "fn" , "path" : "src/util.rs" , "lines" :[ 2 , 4 ], "summary" : "The greeting shown on the kiosk screen." , "summary_source" : "doc" , "signature" : null , "span" :[ 44 , 126 ], "source_utf8" : "pub fn greet(name: &str) -> String {\n format!(\"Hello, {}!\", title_case(name))\n}" , "edge" : null , "direction" : null , "target" : null , "confidence" : null }], "more" : 0 , "next" : null } Pack for a task # --for uses the task terms to select find results, neighbors and source reads. --budget 800 bounds estimated output tokens, not scan size; the footer reports usage and dropped records. # dctx pack --for budget = 800 terms = 2 s:src/util.rs#greet fn L 2 - 4 s:web/app.ts#renderGreeting fn L 10 - 12 s:src/store.rs#Order struct L 4 - 8 s:src/store.rs#checksum fn L 22 - 24 s:src/store.rs#encode fn L 17 - 19 calls:in:s:src/main.rs#main fn src/main.rs L 7 pub id: u 32 , pub qty: u 32 , # end body_tokens = 223 budget = 800 dropped = 0 Which mode? # CLI and one-off chat : pack selected source for a prompt or use the interactive terminal. Agents, short tasks : compare with grep plus narrow file reads first. Agents, long sessions and huge trees : scope the root, find symbols and read exact source. Libraries : embed the Rust facade today; install the Node wrapper with npm install @tejl/dctx , or use CI artifacts for the Python and Go wrappers. CI and prompt caching : pin inputs and measure byte stability and provider cache behavior. Desktop : build the Tauri 0.11 preview; the GPUI rebuild is planned. Measured, in the open # The baseline is grep plus reading files . The 11 November whole-session benchmark measured 20 questions on a private 13-crate Rust workspace with claude-sonnet-5-5 , dctx 1.3.0 and three repeats per arm. Median total tokens [min, max]: grep plus reads 14,904,014 [14,604,149, 15,622,381]; dctx CLI (warm index) 14,157,974 [11,221,908, 15,613,375]. On this corpus and model dctx did not save 25 % tokens. CLI median tokens were -5.01 % versus grep; the pre-registered success rule was not met. The claim is accuracy and bounded context , not token savings: CLI named more required files at about equal or higher token cost. dctx on its own does not save tokens by default. Savings come from a harness or agent system that reuses byte-identical, prefix-stable context across long sessions over a large body of work. It behaves like an advanced caching mechanism, with complete control over every byte of context. There is no measured, citable savings figure for such a system yet. Why this matters . Official strict citation recall medians [min, max]: grep 10.10 % [10.10, 20.73], CLI 14.46 % [8.36, 22.65]. Diagnostic file-level recall medians: 53.77 % and 71.70 %, respectively; this does not replace strict recall. One corpus, one model, three repeats; no significance claim. Corpus and raw answers are private and cannot be published; dctx 1.3.0 is not current HEAD. Under ~200 files, use grep. Choosing how to use dctx covers scoping and CLI usage. Measurement evidence describes what was measured (tool-output bytes and estimated tokens); other-tool protocols are retained only as secondary historical notes. Start and choose your path # What dctx is , four user paths , responsibilities , and two scopes, one binary explain setup and ownership. The documentation index groups modalities, scopes, savings must be measured. See current limits and the specification and roadmap . The core belief: prompt-processing efficiency # Bounded : map answers use estimated token budgets and whole records. Deterministic : identical source snapshots and requests give identical bytes. Read the philosophy and its testable constraints . Quick Start # Use the safe path or the runnable pack and map example . For repeated agent work, see Map mode: context for agents . Map mode: context for agents # Read exact IDs from the result with dctx map read 'ID' --json . See the map guide for commands, budgets and limits. From source # alias dctx = "$PWD/target/release/dctx-cli" Cargo builds dctx-cli ( dctx-cli.exe on Windows); release archives supply dctx . For a local source installation, use cargo install --locked --path crates/dctx-cli and alias dctx=dctx-cli . See CI coverage and desktop exclusions . Use as a library # The public Rust entry point is the dctx facade , available from Git now; crates.io publication is pending . dctx = { git = "https://github.com/Eris-Margeta/dctx" , tag = "v1.3.1" } This example is generated from the workspace doctest : use dctx::{memory::{ CancelFlag , FixedClock , MemorySource }, *}; let mut source = MemorySource :: new (); source. insert_file ( "hello.rs" , b"pub fn hello() {}\n" , 0 )?; let mut session = Session :: builder (source). clock ( FixedClock ( Timestamp ( 0 ))) . cancellation (std::sync:: Arc :: new ( CancelFlag :: new ())). ceiling ( HostCeiling :: base ()) . selection ( SelectionPolicy :: from_texts (& RuleTexts :: default ())). grants ( HostGrants :: PermitAll ) . storage ( StoragePolicy :: Ephemeral { max_bytes: 8 * 1024 * 1024 }). place ( "demo" ). view ( "pack" ). build ()?; let mut output = VecSink :: new (); session. pack (& PackRequest :: new (), & mut output)?; println! ( "{}" , std:: str :: from_utf8 (output. as_bytes ())?); The host supplies selection rules and storage policy; FsSource does not load .gitignore automatically. Read the before embedding it. Python, Node and Go wrappers over dctx rpc live in packages/python , packaging/npm and packages/go ; they are built and tested in CI. Install the Node wrapper with npm install @tejl/dctx ; use CI artifacts for Python and Go. Versioned pack JSON # For a pinned external runtime, use dctx pack --for 'fix alpha_body' --json . The schema field is dctx.pack/1 ; dctx pack --schema prints the shipped JSON Schema . Every included source fragment pack's source snapshot identity. Unknown source commits are explicitly null . CLI Reference # dctx context returns ranked context for a file, symbol name or stable node id; dctx rpc serves the versioned engine protocol used by the language wrappers ( protocol ); send hello first. dctx read is dctx map read . dctx map export writes the whole graph as JSON or Mermaid. dctx languages lists every supported language and its tier. dctx doctor lists visible dctx binaries, their scopes, SHA-256 checksums and Run dctx --help , dctx pack --help and dctx map --help for the complete reference and dctx --version --verbose for feature and precision limits. See map commands and limits , exit codes , templates , and plugins . does not enable it. Organization policy and dctx policy explain are planned. Language tiers # dctx languages prints this table ( --json for tools, --markdown for this block) from the one registry that also drives dctx --version --verbose ; a test fails when the block below differs from it. full : symbols and call edges. Call edges are lexical, not type-resolved: they come from names, scopes and imports, never from a type checker, and ambiguous references are dropped. outline : symbols only; no call edges are promised. Shell function bodies can yield same-file call guesses, but v1 does not promise shell call edges. docs : headed sections. Confidence : guess marks the heuristic outline families, and every record from those files carries confidence guess ; structural means a dedicated lexer or deterministic document rules. Security & Privacy # Pack and map run locally and have no telemetry , call no model and make no network calls . Selection happens before any byte is read, hashed, .gitignore , .dctxignore , global ignore file Excluded from normal selection; --debug-ignored shows ignored path metadata without reading content The global ignore file is <config dir>/dctx/ignore : $XDG_CONFIG_HOME/dctx/ignore or ~/.config/dctx/ignore on Linux and macOS, %APPDATA%\dctx\ignore on Windows. dctx does not read Git metadata, so .git/info/exclude and Git's core.excludesFile are not applied: copy those patterns into .dctxignore or DCTX_INDEX_IGNORED=1 skips those ignore texts, so leave it unset when relying on them. Built-in sensitive-file and .git exclusions still apply. Sensitive files such as .env , private keys and credentials are omitted from .git at any depth is never listed or read by map, and is never read by pack. Symlinks are never followed; final-component file opens use O_NOFOLLOW . The privacy contract and deny list and map privacy guide explain the boundary. Report vulnerabilities privately through SECURITY.md . The release check tests socket activity under strace -f and reports SKIP where tracing cannot run. Plugin network and see current plugin limits . Open source and maintenance # dctx and its desktop app are Apache-2.0 , copyright Eris Margeta. Every modality stays open. GitHub Sponsors and maintenance agreements fund upkeep without changing the license. See trademark policy , NOTICE , Rust dependencies and npm dependencies . Where it comes from # dctx started in 2025 as dircontxt in C and was rewritten in Rust in 2026. The changelog and legacy-c/ preserve that history. Contributing # Read CONTRIBUTING.md , the specification and crate map . Website · Documentation · For AI evaluators · llms-small.txt · llms.txt · --- url: https://www.dctx.internet.technology/docs/start/ title: What dctx is source: https://github.com/Eris-Margeta/dctx/blob/main/docs/START.md --- Document: `docs/START.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/start/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt What dctx is View source · Edit on GitHub · Markdown · docs/START.md · 1,655 words · updated 13 November 2026 On this page Choose your path Safe path in ten minutes Responsibilities Two scopes, one binary Choose your path # One giant folder # Install the system binary , choose a relevant package, and put exclusions in that root's .dctxignore before the first query: parent tree. Use an ID with map read . There is no general receipt yet; --json exposes freshness, precision and pagination. Each invocation checks before warming an index; --in only filters after indexing. Many small projects # Start with dctx map find , then dctx map read using its exact ID. Expect source plus Inspect the dry run before applying cleanup; purge requires --yes . See cache controls . Indexes live in an engine major.minor subdirectory (for example 1.3 ) of the cache parent, which is DCTX_CACHE_DIR or the platform default v2 cache root; patch releases share it, and Agent builder embedding a library # Agent builder embedding a library: project library with its own pinned binary (Python, Node or Go wrapper over dctx rpc ); never parse or slice pack text. Pitfall: re-implementing engine logic. The Python , Node and Go wrappers over dctx rpc are built and tested in CI. Install Node with npm install @tejl/dctx , which includes a pinned @tejl/dctx-<platform> optional dependency; use CI artifacts or a checkout for Rust facade from tagged Git, in the library doctest . For subprocess use: ID to map read --json for source_utf8 . Keep engine selection and rendering in pack text. Named context adds stable chunk IDs and opt-in delivery sessions: use dctx context TARGET --session ID --dedupe . Delivery history lasts A Rust facade Session is an in-process API object. See the scope contract . Team / enterprise admin # Team / enterprise admin: system binary via package manager, signature + SBOM verification, one pinned version fleet-wide. Pitfall: mixing project and system versions without checking ( dctx doctor ). SHA256SUMS entry; package-manager distribution, signed CLI binaries and a Expect version and feature/precision limits. dctx doctor lists the dctx use release procedure , testing and security reporting for the current controls. Signed 1. Install the system binary # Download the archive for your OS and architecture and SHA256SUMS from GitHub Releases . On Linux use sha256sum ARCHIVE , on macOS shasum -a 256 ARCHIVE , or on Windows PowerShell Get-FileHash ARCHIVE -Algorithm SHA256 , replacing ARCHIVE with the Extract the archive and put dctx ( dctx.exe on Windows) on your user PATH . 2. Choose one project and inspect one answer # Use a small project or a relevant sub-root. Check .gitignore and .dctxignore before scanning; leave DCTX_INDEX_IGNORED unset. From that directory: Replace Config with a symbol or heading in your project. Read a returned ID with dctx map read 'ID' --json . The JSON includes verified source bytes as source_utf8 and reports precision, freshness and pagination. Keep the same 3. Use the CLI from your shell or agent # Replace ID_FROM_FIND with an exact ID returned by find . Use the same commands through an agent's shell tool. See the map guide for bounds and pagination, and agent guidance for shell usage. 4. Measure before changing anything # It reports body_tokens , budget and dropped , using estimated tokens rather See measurement evidence and CI/cache guidance . Responsibilities # (planned) . Prebuilt archives with SHA256SUMS , cosign signatures, SBOM and provenance are available; see download verification . Release archives with cosign signatures, SBOM and provenance, cache caps, dctx doctor , journals (planned), receipts (planned) CLI commands and agent-setup guidance For current CLI exclusions, use .gitignore and .dctxignore ; the unified policy Two scopes, one binary # The system dctx on PATH belongs to you and your agents. A binary installed by a project library lives inside that project (virtualenv, node_modules), pinned and managed by that package manager. Same signed engine, different owner. Interactive agents call the system binary; application code and CI call the project binary; a library never silently falls back to PATH. DCTX_BIN , their own platform package (Python, Node) or a versioned user cache, and never search PATH . Until they are published, install them from CI The CLI cache lives in <cache-parent>/<engine-major.minor>/ under the platform-specific dctx/v2 parent (or DCTX_CACHE_DIR ), so engines 1.2 and 1.3 scopes ). A version/path line in every pack is planned. Today dctx rpc reports the engine version in hello , and dctx doctor lists the dctx explicitly, and use separate absolute DCTX_CACHE_DIR locations when two Continue with the documentation index , modalities or engine specification . --- url: https://www.dctx.internet.technology/docs/modalities/ title: Choosing how to use dctx source: https://github.com/Eris-Margeta/dctx/blob/main/docs/MODALITIES.md --- Document: `docs/MODALITIES.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/modalities/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt Choosing how to use dctx View source · Edit on GitHub · Markdown · docs/MODALITIES.md · 1,735 words · updated 13 November 2026 On this page Available surfaces and publication status Choose by task Human, one-off: pack to clipboard Short agent task: grep can be enough Huge trees: scope before indexing CI / prompt-cache prefix stability Rust library: embed the facade Desktop app: Tauri preview today Python, Node and Go wrappers Compare dctx with grep plus reading files , and choose by the work you need to Available surfaces and publication status # Prebuilt archives , or build from source One-off chat ( pack --clipboard ), shell agents, scripts and CI; run dctx for the terminal menu Rust library ( dctx facade) Tagged Git dependency in the library section npm install @tejl/dctx for Node; CI artifacts for Python and Go; see language wrappers Calling the engine over dctx rpc from Python, Node or Go projects From version 1.3.1, the npm release publishes @tejl/dctx with pinned @tejl/dctx-<platform> optional available for system installation or an explicit DCTX_BIN path. Choose by task # find -> read --json , with skeleton for orientation Deterministic pack or scoped map output saved as an artifact Human, one-off: pack to clipboard # function matters. Narrow the root first, or use map reads. Pack's --ext rs,toml and --small 1 filters can restrict extensions and file sizes (MB); they are Short agent task: grep can be enough # grep -R -n -F --include= '*.rs' 'struct Session' crates/dctx/src dctx map find Session through the existing shell. Verbose agent instructions For your project, use the exact ID returned by find . Both text read and read --json include verified source bytes; JSON carries them in source_utf8 . Skeletons show declaration signatures without bodies. If an answer has more and next , pass that opaque next value with --cursor on the same request, and count the Huge trees: scope before indexing # Map's shared cache stores a lifecycle ledger ( ledger.v1 ), policy ( policy.v1 ), The product hard cap is 2 GiB (2,147,483,648 accounted bytes) across the shared filesystem-size guarantee. cache config --max-bytes can only tighten it. --place selects the scan root. --in src narrows find/grep matches after indexing; --budget , --limit and --cursor bound answers, not the tree scan. Use existing .gitignore and a .dctxignore at the chosen root to exclude data, For example, merge these project-specific entries into .dctxignore : /data / /generated / /archive / The host loads the global ignore file, root and nested .gitignore rules, then the root .dctxignore . Built-in sensitive-file and .git exclusions still apply. The global ignore file is <config dir>/dctx/ignore : $XDG_CONFIG_HOME/dctx/ignore or ~/.config/dctx/ignore on Linux and macOS, %APPDATA%\dctx\ignore on Windows. dctx does not read Git metadata, so .git/info/exclude and Git's core.excludesFile are not applied; put those patterns in .dctxignore or the Do not set DCTX_INDEX_IGNORED=1 when relying on these ignore rules. The built binary documents these environment variables , not scan-limit flags: DCTX_MAX_SOURCE_BYTES = 268435456 DCTX_MAX_RECORDS = 250000 DCTX_MAX_ENTRIES = 25000 \ cache cap. A different absolute DCTX_CACHE_DIR selects a separate cache CI / prompt-cache prefix stability # --tree-stamps=off for stable prefixes. For map, leave --meta off to exclude changing snapshot, generation and age metadata. The stability report measured 33/33 text cache hits, billed tokens or whole-session latency. A bare touch leaves default Rust library: embed the facade # The supported entry point for Rust integrations is the dctx facade , which exposes Session , SnapshotRequest , MapRequest , PackRequest , sinks, The facade is available from Git now; crates.io publication is pending . In your application's Cargo.toml : dctx = { git = "https://github.com/Eris-Margeta/dctx" , tag = "v1.3.1" } The ten-line pack example is compiled and run as a workspace doctest . It uses an in-memory source and The example's println! belongs to the caller. A VecSink collects the encoded For filesystem use, open an FsSource at a scoped root and supply a live Clock . The source does not automatically load .gitignore ; the host must pass its ignore-rule texts through RuleTexts / SelectionPolicy . Choose storage ceilings Desktop app: Tauri preview today # The desktop app is a Tauri 2 app, currently the 0.11 preview. It uses dctx-desktop-api and the shared Rust facade. Build it from source using the app's quick start ; Python, Node and Go wrappers # Thin wrappers over the versioned dctx rpc protocol live in packages/python , packaging/npm/dctx (which also forwards the dctx CLI command) and packages/go . Each starts the npm install @tejl/dctx ; npm includes the matching pinned @tejl/dctx-<platform> from the GitHub release archives that has dctx rpc . Their arguments carry full CLI authority, so never pass untrusted values as --place , --output or dash-leading arguments. --json map answers. Use the Rust facade when you need an in-process engine. --- url: https://www.dctx.internet.technology/docs/map-mode/ title: Map mode guide source: https://github.com/Eris-Margeta/dctx/blob/main/docs/guides/MAP-MODE.md --- Document: `docs/guides/MAP-MODE.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/map-mode/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt Map mode View source · Edit on GitHub · Markdown · docs/guides/MAP-MODE.md · 2,694 words · updated 13 November 2026 On this page Definitions outside the index Commands Trace: how A reaches B Impact: what depends on a symbol Languages and precision Index, cache and privacy Two worked examples reads. It builds the index automatically; there is no user index command. in SPEC-MAP-MODE are not the current CLI contract. For an agent using a shell, see the agent snippet . Definitions outside the index # For find , neighbors , explain , read , grep , trace , impact and context , a literal local JSON adds defined_outside_index , an array of objects with path and hint . path dependencies, plus sibling Python from and Rust use targets. It searches --also DIR is repeatable on every map verb, pack and context . Directories carry their root directory label, for example s:app/main.py#run and s:lib/shared.py#shared . Root labels must be distinct. Each root keeps its own changing the order of --also does not change identities or reuse another set's Commands # Read a node's verified source; a long node pages with --cursor . dctx read is the same verb. A file's (or m:<path> 's) declaration signatures in source order, no bodies. Shortest edge path (calls, imports, contains; either direction; at most 8 hops), or no path . Copy node IDs from results: m:sample.py names a module and s:sample.py#PythonBeacon names a symbol. dctx map <verb> --help prints each The following option descriptions follow dctx map --help ( source ): Stage timings and the five slowest files on stderr ( DCTX_PROFILE=1 is the same switch). Output tokens, 1..2000; explain max: 1000. read with no --budget uses the 2,000-token hard cap. map : 1..3; neighbors : 1..4. explain and read take no depth. map , find , neighbors page size; explain and read accept only 1. hubs : 1..60 lines, default 20. Refused. Pass the previous page's next value to --cursor . find : comma-separated node kinds. find or grep : restrict to a relative path. -i , --ignore-case grep : ASCII case-insensitive match. neighbors : comma-separated edge filter. neighbors : relation direction. read : exactly those absolute source lines inside the node; --full permits 400. Environment bounds: DCTX_MAX_SOURCE_BYTES (total source bytes one scan may read, default 1 GiB), DCTX_MAX_RECORDS (files, symbols and edges one index may hold, default 1000000), DCTX_MAX_ENTRIES (files and directories one scan may visit, default 100000) and DCTX_FRESHNESS (see below). The parser also accepts these --kind values: method , struct , enum , trait , impl , const , macro , class , interface , symbol , module , package , place , test . Edge names also include contains , implements , uses-type , tests , documents , reexports . The token estimate is ceil(2 * UTF-8 bytes / 7) , not a tokenizer guarantee. Trace: how A reaches B # trace follows directed call and import/reference edges in the indexed graph. ambiguous. Missing endpoints and disconnected symbols return no path within bounds . A depth cutoff, excess shortest paths or a byte cutoff adds a truncated: line. A path is retained whole or dropped whole. --max-depth N ( --depth N ) --json emits an object with v: 2 , verb: "trace" , paths (arrays of locations), counts.paths , bounds and truncated . A location contains id , file , line , symbol and depth (zero for trace hops). Counts describe the returned paths. An empty result has paths: [] . Impact: what depends on a symbol # impact lists direct identifier references and call lines, then distinct caller depth; cycles do not repeat a caller. A truncated: line reports a depth, --max-depth N ( --depth N ) --json emits v: 2 , verb: "impact" , files , counts , bounds and truncated . Each file group contains file , direct , callers and counts ; locations use the same fields as trace, with direct depth: 1 and transitive depth >= 2 . Page counts contain files , direct_sites and transitive_callers ; group counts contain the latter two. Empty results have files: [] and zero counts. Both verbs also accept dctx map trace / dctx map impact , --place PATH and repeatable --also DIR . They share the deny list, root labels, cache identity, Neither verb uses --budget or cursors. Bounds errors name the verb, option, Engine RPC advertises trace and impact and returns their exact JSON pages. Languages and precision # This table is the output of dctx languages --markdown for the release build ( dctx languages --json gives the same data as JSON). Extension matching is case-insensitive: Upper.RS is indexed as Rust. .js , .mjs , .cjs , .jsx .ts , .mts , .cts , .tsx .py , .pyi .c , .h , .cc , .cpp , .cxx , .hpp , .hh .kt , .kts .rb , .rake , .gemspec , Rakefile , Gemfile .php , .phtml , .inc .vue , .svelte , .astro , .html , .htm .scala , .sc .f90 , .f95 , .f03 , .f08 , .f , .for .pl , .pm , .t , .psgi .groovy , .gradle .ps1 , .psm1 , .psd1 .ex , .exs .ml , .mli .erl , .hrl .v , .vh , .sv , .svh .tf , .tfvars , .hcl .sql , *.sql.in .clj , .cljs , .cljc , .edn .lisp , .lsp , .cl .scm , .ss .json , .jsonc , .toml , .yaml , .yml .sh , .bash , .zsh , .bats .mk , Makefile , GNUmakefile Dockerfile , Containerfile .pas , .pp , .dpr .graphql , .gql .md , .markdown .adoc , .asciidoc Tiers: full extracts symbols and call edges, outline symbols only, and docs headed sections. Confidence guess marks heuristic outlines, whose records carry confidence guess . See language coverage . Rust uses syn in release builds (the syntax-rust feature, reported as parser dctx-lex-rust/syn-<version> with syntax coverage), for supported Rust syntax resolution or macro expansion. dctx --version --verbose lists the parsers and JSON answers expose precision.coverage , precision.completion and precision.parser (the default structural parser identity is dctx-structural/3 ). The model distinguishes structural , syntax and opaque coverage from complete , partial and refused completion. These labels describe extraction, separately from edge checks empty records for OpaqueBeacon in sample.unknown . Index, cache and privacy # DCTX_FRESHNESS=strict_live hashes every file on a warm start. Exact source The retired per-worktree SQLite cache selector ( map/storage.rs ) has been deleted; the CLI does not read DCTX_MAP_CACHE . The shared cache stores ledger.v1 , policy.v1 , serialized generations and copies of all source contents. See Choosing how to use dctx Set DCTX_CACHE_DIR to an $XDG_CACHE_HOME/dctx/v2 , or ~/.cache/dctx/v2 DX-ARCH-08 : time-based expiry, a system status accepts --root PATH ; gc accepts --root PATH , --max-bytes N and --legacy . Applying purge requires --yes and either --root PATH or --all . cache config without arguments shows persisted policy; auto on|off controls auto-clean, and --max-bytes can only tighten the cap. Pack, map, template, --no-auto-clean or DCTX_AUTO_CLEAN=0 disables that slice. ( <config dir>/dctx/ignore : $XDG_CONFIG_HOME/dctx/ignore or ~/.config/dctx/ignore on Linux and macOS, %APPDATA%\dctx\ignore on Windows), root and nested .gitignore rules, then the chosen root's .dctxignore . DCTX_INDEX_IGNORED=1 skips those ignore texts; built-in sensitive-file and .git exclusions still apply. The core does not read Git metadata or run Git, so .git/info/exclude and Git's core.excludesFile are not applied. The optional Git plugin has separately disclosed authority; see Plugins . Two worked examples # map_cli.rs . The test checks fragments, columns or counts. Create a project containing sample.py : def PythonBeacon (): For the second example, add sample.unknown with: def OpaqueBeacon (): Expected JSON contains this exact fragment and does not contain OpaqueBeacon : crate map . --- url: https://www.dctx.internet.technology/docs/agents/ title: Agent snippet source: https://github.com/Eris-Margeta/dctx/blob/main/docs/guides/AGENTS-SNIPPET.md --- Document: `docs/guides/AGENTS-SNIPPET.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/agents/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt AGENTS.md snippet: task context from dctx View source · Edit on GitHub · Markdown · docs/guides/AGENTS-SNIPPET.md · 196 words · updated 9 November 2026 On this page Notes for coding agents Paste the section below into a project's AGENTS.md (or CLAUDE.md ) so coding agents start from dctx context. Notes for coding agents # $TASK is the task description. dctx runs map find on the names the text mentions (backticked words, snake_case, camelCase, a::b , then longer plain words), then map neighbors and map read on the best hits, and prints whole lines Name things in the text: --for main or --for Session works, but a sentence such as "how does caching work" only backticks, as in --for 'fix `run` in the pack command' . Then narrow with dctx map find , dctx map neighbors <id> and dctx map read <id> as needed ( dctx map --help ). --- url: https://www.dctx.internet.technology/docs/plugins/ title: Plugins guide source: https://github.com/Eris-Margeta/dctx/blob/main/docs/guides/PLUGINS.md --- Document: `docs/guides/PLUGINS.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/plugins/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt Plugins View source · Edit on GitHub · Markdown · docs/guides/PLUGINS.md · 980 words · updated 7 November 2026 On this page Bundled Git plugin and consent CLI reference Desktop: Settings > Plugins Strict build Trust and signatures What is not yet available Bundled Git plugin and consent # The default CLI includes dctx/git version 1.0.0 , with alias dctx git and the verbs status and protect . The catalog defaults to enabled. A fresh CLI without a consent record reports enabled with needs-consent ; shipping the dctx git is a plugin alias, not a general Git passthrough. The bundled manifest capabilities Required file.read Project .gitignore , at most 1,048,576 bytes. Required file.write Existing project .gitignore only ( create=false ); growth at most 4,096 bytes, total at most 1,052,672 bytes. Optional program.run Program git , operation git.add-ignore , resource git-admin:stage-ignore , output at most 65,536 bytes. does not run Git, read .git/ or use Git hashes for identity. --approve records consent for the displayed capability set. New installations remain inactive until enabled; combined install --enable requires --approve . across updates. enable --project PATH scopes consent to a project; omitting it uses user scope. disable --project PATH is accepted/reported, but the current The CLI additionally separates enablement ( inactive , enabled , disabled ) from consent ( inactive , needs-consent , granted , disabled ) and reports with consent unavailable and worker excluded . CLI reference # ( render.rs ) and parse.rs : dctx plugin , dctx plugin help , --help and -h show plugin help. metadata; search --refresh requests a fetch. List and help start no worker, fetch nothing and do not create a project .dctx/ directory. offline bundle. URL/file sources require --id ; the parser also accepts --enable --approve with those sources. update --check reports a candidate verify --refresh-trust requests a revocation freshness check. Bundled updates come with the containing CLI/app release. remove masks the bundled copy when run requires the -- separator. The Git alias rejects that separator. The parser recognizes --json for plugin and alias requests, including run , Desktop: Settings > Plugins # Open Settings > Plugins to inspect bundled/installed source, version, state, requested capabilities and the last failure. Refresh plugins reloads the list. Enable and Disable call the host management API. Grant consent opens a review dialog with plugin ID, version, artifact SHA-256, capability descriptions and exact grants/bounds. Confirm grant records user-wide consent for all projects; Cancel closes the dialog. Check for update reports cached information and explicitly states that plugins.ts ; opening settings does Strict build # The dctx library includes the optional plugin-runtime feature in its defaults. Hosts requiring the engine without that runtime must disable defaults and select pack , map , templates , fs , segments , cache as needed. The runtime adds the host, platform and protocol For the CLI , select --no-default-features --features strict when building. Cargo features are additive: selecting strict alone leaves defaults enabled. This composition excludes dctx-plugin-host , dctx-plugin-platform and dctx-plugin-git from strict does not mean that every crate whose name contains plugin disappears. Trust and signatures # (test fixtures use test keys). Unverified: a completed production release What is not yet available # Public plugin publication through this CLI. There is no plugin publish command. The default discovery URL is https://example.invalid/dctx/index.json ; a live public registry/release publication is unverified . Local index Sources: plugin design , native platform limits , Ed25519 verification , and the crate map . --- url: https://www.dctx.internet.technology/docs/spec/ title: Specification source: https://github.com/Eris-Margeta/dctx/blob/main/docs/SPEC.md --- Document: `docs/SPEC.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/spec/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt The dctx Context Management Specification View source · Edit on GitHub · Markdown · docs/SPEC.md · 9,224 words · updated 13 November 2026 On this page Contents Part I — Principles 1. Purpose and the workflows served 2. The core belief: prompt-processing efficiency 3. Zero RAG defects 4. Privacy and authority Part II — Model 5. Identity 6. The graph: nodes, ids, outcomes 7. Edges, confidence and provenance 8. Precision labels 9. Freshness Part III — Answers 10. The verbs 11. Page formats and byte stability 12. Tiers, deltas, deduplication and compression levels 13. Token estimation Part IV — Policy 14. One language: DTS v2 15. The seven-layer policy lattice 16. Organization bundles, signing and enrollment 17. Explain and receipts Part V — Index 18. Segments, manifests and the per-file fact store 19. Freshness check and incremental rebuild 20. Cold build 21. Ranking Part VI — Extension 22. Core, surface or plugin: the decision procedure 23. Plugin protocol and its v1.x extensions 24. Surfaces 25. Blast radius (target) 26. Learnings (target) Part VII — Assurance 27. Dependencies and build profiles 28. Conformance suite 29. Formal models 30. Versioning and compatibility Part VIII — Delivery 31. Roadmap and acceptance gates 32. Non-goals Appendix A — Lineage Appendix B — Comparison with Trail-Code Appendix C — Reserved names Appendix D — Document map docs/research/trail-code-2026-10 (dctx 17dff0b , Trail-Code 0.23.1) This document specifies dctx , a context engine for AI-assisted software development. It is normative where it uses MUST , MUST NOT , SHOULD and MAY (RFC 2119). Every claim it makes about the product is either marked landed (present in the repository today), contract (a versioned contract in docs/design/contracts/ that is partly implemented) or target (specified here, not yet built), and every target values cite the pinned benchmark in docs/research/trail-code-2026-10/REPORT.md or the Contents # 1. Purpose and the workflows served # dctx turns a directory of source code into the smallest, most cache-stable, provably authorized set of bytes that lets a model or a human act correctly — and it can prove dctx map outline, find , read ; desktop app (free) dctx pack (full / diff), templates, clipboard library facade ( crates/dctx ), bindings 2. The core belief: prompt-processing efficiency # philosophy and whole-session benchmark . MUST satisfy the five PPE constraints: landed ( dctx_core::budget , API-PORTS-v1 BoundedSink ) tier layering remains target (§12.1); on 2026-11-06, 0495f5f preserved 33/33 text and 33/33 JSON answers after unrelated comment edits on three pinned local corpora; all identical over five runs, paired-answer M7 = 1.0 ( protocol and limits ); historical baseline 0/63 (§31.0) landed ( precision.* , freshness.* in the wire format) Rule. A feature without an acceptance gate stated in M1–M8, or in a latency, 3. Zero RAG defects # defect corpus — fixtures with a positive control per class — that dctx conformance Records are syntax-owned spans; read returns the whole node or a marked prefix with a continuation; records are never split There is no incremental index and no stale flag. Every CLI process re-walks the tree and re-hashes the selected files; a persisted generation is reused only when every content digest still matches, and any change rebuilds the whole generation. Inside one session read re-hashes the bytes against the snapshot digest and refuses with SourceChanged when they differ. The CLI always takes strict snapshots, so freshness.state is always "verified" (the library reports "metadata" only for a FreshnessMode::Metadata request) Path + qualified-name ids with ordinals; explicit moved , gone , ambiguous outcomes contract — lexical ranking landed; graph edges are not emitted by the shipped CLI (TC-F01); the resolver is landed in crates/dctx-map-resolve but not wired (§7); typed rung target landed for map verbs; the legacy tree ( dctx . -t ) and pack are unbounded (974 KB and 8.7 MB measured) and are not conformant surfaces M5 inside M2; dctx bench tokens (§28) embedding:<model> — labeled, optional, never default. 4. Privacy and authority # Selection before content. A path is classified ( Include , Exclude , OmitContent , DebugVisible ) before any byte of it is read, hashed, parsed or cached. Exclude , OmitContent and DebugVisible never authorize content. Landed; evidence: read-spy tests in crates/dctx-adapter-fs/tests/privacy.rs and crates/dctx-map-query/tests/source_privacy.rs . Rules. Built-in defaults, repository .gitignore files (read as plain text), .dctxignore and policy ( privacy.ignore ) combine. Landed for Secret-shaped files (landed for v1). A strict, built-in deny covers .env , .env.* , *.env , .envrc , *.pem , *.key , *.p12 , *.pfx , *.jks , *.keystore , id_rsa , id_dsa , id_ecdsa , id_ed25519 (and _ / - suffixed variants), .netrc , _netrc , .npmrc , .pypirc , .pgpass , .htpasswd , .git-credentials , credentials , credentials.<data> , *.credentials.json and secrets.<data> (data = json, yaml, yml, v1 has no override: no --allow-sensitive flag, and no local rule can negate the deny. Policy MAY later add named classes ( aws , gcp , ssh , jwt ). dctx never scans contents to decide. Gate: the adversarial corpus's planted .env value is absent from pack output and from the map cache; the path is listed. Checked for every shape and every command by <repo>/scripts/checks/V1-1.zsh (TC-F08 is closed). No VCS in the core. The core never reads .git/ , never spawns git , never uses Landed ( crates/dctx-map-query/tests/no_git.rs ). No network in the core. No telemetry, no update checks, no model calls. The only legal telemetry value in policy is "none" . Measured: zero socket system calls in Re-check at emission. Policy is checked again before bytes leave the engine, even 5. Identity # Identity is defined by docs/design/contracts/IDENTITY-v1.md and summarized here. Algorithm-tagged first-party SHA-256 of the exact authorized bytes, plus byte length ( crates/dctx-hash ) ObjectKey + language + parser identity and revision + extraction-rule digest Sorted manifest of (path, stamp, ObjectKey ) for the authorized view view digest (target) SHA-256 over the ViewKey framing and the canonical request bytes; printed in the provenance trailer ( --provenance , §11) so a caller can name what it already holds One per layer plus the effective digest (§15); part of ViewKey 6. The graph: nodes, ids, outcomes # Nodes: place , package , module , symbol (with kinds fn , method , struct , enum , trait , impl , const , macro , class , interface , type , test ) and doc sections. Ids are stable, human-copyable strings: A request for an id that no longer resolves returns an outcome , never a silent empty answer: moved (with the new id, from body-fingerprint evidence), gone , or ambiguous (with candidates). 7. Edges, confidence and provenance # Edge kinds: contains , imports , calls , implements , uses-type , tests , documents , reexports . Status. Kinds and the confidence lattice are landed in dctx-map-model ; crates/dctx-map-resolve . The facade index ( crates/dctx/src/index ) emits only contains edges today , so neighbors --edge calls|imports was empty on 140 of 140 Bound by syntax and scope, or by an import that resolves to a file in the view, or supplied by a compiler-grade overlay. Measured expectation: a comparison tool reaches precision 0.94–1.00 at recall 0.10–0.96 with syntax-and-scope binding alone; dctx MUST reach precision ≥ 0.95 before its edges may be shown without a guess label lexer + resolver; lsp:<server>@<version> overlays typed (target) An edge labeled exact that is wrong is a defect , not a statistic. 7.1 The binder (target: dctx-map-bind , pure crate) # fields: receiver (head identifier of the receiver expression), arity , and binding_hint (declared annotation, constructor name or import alias that produced a lexical scopes outward (shadowing honored) -> exact on a unique declaration; dctx-lex-cfg ( tsconfig paths, go.mod , Cargo.toml , composer.json , pyproject , SwiftPM targets) -> exact ; the receiver's type by shallow, deterministic rules — self / this , constructor, typed ; a unique declaration in the view with a compatible kind -> name ; otherwise guess or unresolved. Gates. Measured on the published gold ( docs/research/trail-code-2026-10/data/targets/ , precision ≥ 0.95; recall ≥ 0.88 on rare (comparison 0.93), ≥ 0.81 on collision (0.86), ≥ 0.35 on hub (0.42), ≥ 0.25 on receiver (0.56); zero wrong exact receiver recall ≥ 0.56, interface name-level recall ≥ 0.42, hub ≥ 0.42; exact ∪ typed precision ≥ 0.95; zero wrong exact ; callees question ≥ 10/14 (today 2/14) extends it before the typed rung is promoted. 8. Precision labels # Every answer carries precision.coverage ( structural | syntax | opaque ), precision.completion ( complete | partial | refused ) and precision.parser (for example dctx-structural/1 , syn/2 ). Unsupported files are opaque : listed, Omissions (target, P1). precision.omitted counts paths excluded for reasons other than policy — {binary, unnamed, oversize, capped} — so an agent knows the map is extraction.max_facts_per_file are labeled partial (TC-F07: one 6.7 MB JSON fixture 9. Freshness # read always verifies its own bytes, in every mode (landed). Answers carry freshness.mode and freshness.state . The age in seconds ( age_s ) and the snapshot digest are opt-in ( --provenance , §11), because either in the default page defeats prefix caching (PPE-3). Status: target; today both are in every default answer. Shipped behaviour (v1): the modes above are a target. The CLI always takes a strict snapshot, so freshness.state is always "verified" ; there is no stale flag (R3, §3). 10. The verbs # Outline a node or file ( --depth 1..3 ) — landed; the project root, p: , k: and directory targets as a paged overview — target, P1 (today refused or gone , TC-F05; the only overview is the unbounded legacy tree) Search names and concepts ( --kind , --in ) Relations ( --edge , --dir in\|out\|both , --depth 1..4 ) Exact source ( --lines A-B , --full up to 400 lines, --level ) grep PATTERN (target, P1) status (target) Paging uses an opaque next cursor, never offsets. Every page ends with a next-step hint. Planned additions: dctx map plan (budget planner, §12.5), dctx blast (§25), dctx check (§26). Degradation (target, P1). A budget below the smallest full record MUST return ids only, then more / next , never exit 1 (today 35 of 84 small-budget requests fail with Concept queries (target, P1). find tokenizes the query and identifiers on case, _ , - and whitespace and ranks by token overlap with names, paths and summary ; 11. Page formats and byte stability # Two formats: the text page (default; one record per line; ids first) and JSON v2 ( --json ; no insignificant whitespace; LF-terminated; field order fixed). Both obey: generation, age) is a trailer line behind --provenance , or a JSON field behind --json --provenance (P0 header prerequisite measured on 2026-11-06: all 33 tested text answers start with # <place> <verb> ; all 33 tested default JSON answers omit snapshot, generation and age_s , and are identical over five runs and after an unrelated comment edit. Shipped opt-in flag: --meta ; the specified provenance trailer and --provenance interface remain target. Evidence , TC-F03); the text page carries content: find and map records are id<TAB>kind<TAB>path:L1-L2<TAB>summary ; explain prints signature, summary and edge counts by kind; read prints the source span (P0 status, 2026-11-06: text read carried source in all three measured cases; text explain still printed only id/kind/path. Richer text fields remain target; evidence , TC-F04); JSON v2 omits null fields (target, P0: today thirteen keys per record, many null, so a JSON find fit 4 records where the text page fit 10); paths are root-relative with / separators on every OS; Note (1.0.1, legacy source page). The dctx pack / dctx . text page (the [DCTX_LLM_CONTEXT_SNAPSHOT_V1] envelope) follows the same no-timestamp rule by default: its tree and root lines carry the ID only, with no MOD: and no SIZE: (a size changes on every ordinary edit, and the tree precedes the file blocks), so a bare touch leaves the page byte-identical and an edit keeps the bytes before the edited file as a common prefix. --tree-stamps=on reproduces the 1.0.0 page with MOD:<ms> and SIZE: on every tree line; {{{node.mod}}} and {{{node.size_part}}} remain available to custom templates. Gates. (P0) ≥ 95 % of text answers byte-identical after an unrelated edit (0 of 63 12.1 Prefix-stable tiers (target) # Project outline ( map --depth 1 ) Turn-local answers ( find , read , …) Invariant: a change confined to tier k never alters a byte of tiers < k . Policy cache.breakpoints = ["T0","T1","T2"] makes tier boundaries the cache breakpoints a host maps onto its provider's mechanism. Gate: rendered twice with a change in tier k , the common prefix length ≥ the byte offset of marker k ; M7 ≥ 0.9 across turns on 12.2 View digests # The provenance trailer ( --provenance ) names the answer's view digest (§5). A caller 12.3 Delta answers (target) # --since <view-digest> recomputes the answer and emits only records whose content digest changed, -<id> lines for removed records, and a header base=<view> changed=<n> removed=<m> unchanged=<u> . An unknown base yields the full answer with base=none , never an error. The engine stores record ids and digests per view (not bytes) in a small, user-private, TTL-bound ledger. dctx pack --since <snapshot> applies the same rule to whole files: unchanged files appear as one tree 12.4 Session deduplication (target) # With --session <id> , a record already emitted in the session renders as =<id> unless its digest changed or --full is given. Session 12.5 Budget planner (target) # dctx map plan --budget N <requests…> allocates a total budget by marginal value — planned , used , left . Deterministic greedy over already-scored records. 12.6 Compression levels (target) # --level signature | skeleton | body for read and for pack blocks: Signature, nested declarations and control-flow keywords; bodies elided as … N lines The level is part of the view digest. Defaults: map records use signature , read uses body ; DTS MAY set levels per selection (for example skeleton for tests/** ). 13. Token estimation # The portable estimate is ceil(2 × UTF-8 bytes / 7) (landed). A host MAY supply an 14. One language: DTS v2 # sealed ContextPlan IR with per-section digests ( docs/design/contracts/DTS-v2.md , crates/dctx-template ). Every mode — pack, map, Requested facts, parsers, extraction limits ( max_facts_per_file ) PLUGINS / PLUGIN privacy.ignore += [ "*.pem" , "*.key" , "secrets/" , ".env*" ] privacy.secret_classes = [ "aws" , "gcp" , "ssh" , "jwt" ] parsers.allow = [ "syn" , "structural" , "opaque" ] agents.hosts.allow = [ "shell" ] learnings.kinds = [ "decisions" , "guardrails" ] enabled = [ "dctx/git" ] denied = [ "dctx/ci-github" ] allow = [ "file.read:.gitignore" , "file.write:.gitignore" ] languages = [ "rust" , "typescript" ] learnings.kinds = [ "decisions" ] Compiler obligations: known keys only; += only on append-only list fields; every existing DCTXIR envelope with section kinds POLICY = 16 , TENANT = 17 (18–31 15. The seven-layer policy lattice # Today's rule — effective_permission = host_grant ∩ organization_ceiling ∩ session_selection (product contract C03) and the plugin grant lattice M ∩ U ∩ O ∩ H ∩ S(t) ∩ A — generalizes to seven layers. Each layer can only narrow the layers above it. Hard caps (2,000 tokens, 8 MiB per file, 2 GiB cache), network = none , telemetry = none .dctx/policy.dts : selections, omit rules, templates, learnings location Monotone narrowing. effective = fold(narrow, L0 … L6) per field: set AND for permissions and OR for required / deny . A widening attempt is a typed compile error naming the layer and field — never a silent clamp. Unreadable policy refuses. A present bundle that fails verification blocks every mode except dctx policy explain . Policy epoch. The effective digest is part of ViewKey and of every plugin Tenants. A tenant is a named narrowing selected by L3 or L4, or requested by a Property P9 (monotone policy). For random layer stacks, the effective value is within every layer field-wise, and a widening at layer k fails naming k . Mutation 15.1 Locations # /Library/Application Support/dctx/org/ (MDM-deployable) $DCTX_ORG_POLICY MAY point at a bundle. The library never discovers locations 16. Organization bundles, signing and enrollment # A .dctxpol bundle reuses the plugin offline-bundle container (bounded table of named payloads with lengths and digests; no compression, no links): policy.dts , tenants/<id>.dts , trust/keys.json , manifest.json , manifest.sig . The signature is Ed25519 over dctx-org-policy-v1 ‖ manifest bytes , verified by crates/dctx-ed25519 . Enrollment. dctx policy enroll --fingerprint <hex> <bundle> pins the Updates. A monotonic sequence is accepted forward only; downgrades are refused; Distribution is any file channel: MDM, configuration management, a repository the 17. Explain and receipts # dctx policy explain [field] prints each effective value, the layer that set it and fingerprints in the local, user-private receipt log. dctx policy receipts --since <t> 18. Segments, manifests and the per-file fact store # The index is a set of immutable, checksummed segments ( docs/design/contracts/SEGMENTS-v1.md , crates/dctx-map-segment , crates/dctx-adapter-store ) under the cache root. No SQLite, Identical files parse once across roots (shared FactKey ). for recovery (landed protocol; formal model in docs/formal/dctx-cache ). cache gc --dry-run reclaimed 0 bytes, TC-F02). 19. Freshness check and incremental rebuild # Status: target, not implemented. The shipped engine has no stamp-only pass, overlay or Stamp pass. Walk the inventory (names, sizes, mtimes; excluded directories are Digest pass only for entries whose stamp differs, plus the query's dependency scope under strict_live . read always verifies its own bytes. Rebuild. Changed files reparse one fact segment each; their nodes and edges are Warm find / neighbors / read , small and medium corpora Warm find / neighbors / read , largest corpus (core, 3,190 files) 1.45 s, 370 MiB (comparison callers 0.83 s) 20. Cold build # Parallel parsing with a bounded parser thread pool ( std::thread::scope , ≤ available file ( extraction.max_facts_per_file , default 10,000); excess configuration and JSON leaves collapse into one partial module node. Gate: cold build ≤5 s and peak RSS ≤150 MiB on the pinned corpus; persistent bytes 21. Ranking # 22. Core, surface or plugin: the decision procedure # 13 lexer crates covering 15 language variants (Rust, JS, TS, TSX, Markdown, Python, Go, Java, C/C++, JSON/TOML/YAML, C#, Kotlin, Ruby, PHP, Swift); syn adapter Git ( .gitignore protection, staging, vcs.changes ) 23. Plugin protocol and its v1.x extensions # TLA+ models with mutation witnesses ( docs/design/PLUGINS.md , docs/formal/dctx-plugins ). 23.1 New capabilities and hooks (target, negotiated minor versions) # Bounded {path, added, removed} hunks; paths filtered by current selection 23.2 The compiler-grade overlay ( dctx/lsp , dctx/scip ) # asks for definitions and references of the view's name -confidence and unresolved exact (lsp:<server>@<version>) . --no-overlay disables it per request. SCIP import is the batch variant for CI. Neither is a default; neither changes FactKey . 24.1 CLI # One binary: dctx (pack, map, template, cache, plugin, policy, agent, learn, check, 24.2 Library facade # crates/dctx is the stable API for every surface ( docs/design/contracts/API-PORTS-v1.md ). 24.3 Agent hooks (target) # dctx agent install <host> [--project] renders, from the effective policy, the host's own configuration fragment: a statusline that runs dctx map status , a session-start and the guidance "use dctx map find / read before grep and cat". Installation is a ( dctx agent uninstall ). Organization policy can allow, require or forbid hosts. No 24.4 Desktop # The desktop app is free, forever . It is a surface over the same facade: snapshots, 25. Blast radius (target) # dctx blast traverses reverse adjacency (callers, implementors, tests, documents) from a set of changed spans, bounded like neighbors . The graph side is core. The change side Snapshot diff (default). dctx blast --from <snapshot> compares the current VCS supply. The git plugin's vcs.changes returns hunks for --staged , --branch <name> and similar; the core maps hunks to node spans. Formats: text records, JSON, and --format pr-comment (Markdown). Posting the comment is a network plugin. Gate: ≤100 ms warm for a 10-hunk change on the pinned corpus. 26. Learnings (target) # .dctx/learnings/<kind>/<slug>.md ; kinds decisions , guardrails , preferences , skills ; policy may narrow kinds and size Markdown; first heading is the title; a fenced dctx block with applies: ids, since: snapshot, status: active \| retired , optional enforce: true Ordinary d: doc nodes with documents edges to the ids they name; find --kind learning ; boost when applies meets the focus set dctx learn add <kind> "<title>" [--applies <id>…] . The core writes only into .dctx/learnings/ and only on an explicit user action For each changed node (§25), lists guardrails whose applies covers it or its neighbors at depth 1. Advisory; exit non-zero only with --strict and an enforced active guardrail A learning that applies to a gone id is reported orphaned ; nothing is deleted automatically Only via dctx learn import with body-fingerprint binding; labeled src=import:<tag> ; served only while fingerprints match 27. Dependencies and build profiles # The current dependency inventories are THIRD_PARTY.md and THIRD_PARTY_NPM.md ; inspect manifests and features for an 27.1 The rules # Core crates are std-only. dctx-hash , dctx-core , dctx-ports , dctx-map-model (without wire-json ), dctx-map-segment , dctx-template , dctx-pack , dctx-map-resolve , dctx-map-bind , dctx-plugin-protocol , the hand-written lexers, dctx-adapter-fs , dctx-adapter-store , dctx-adapter-cache and dctx-map-scan have zero third-party normal dependencies and forbid unsafe ; CI checks cargo tree -e normal per crate. Every third-party crate in a default build is listed in docs/DEPENDENCIES.md with version, licence, unsafe count, reason and the plan for it. CI fails if the Ed25519 stays for security and trust. ed25519-dalek (exact pin, std feature only, verify-only) is a vetted, widely audited security crate and the single disclosed exception to the zero-third-party rule, behind feature trust . It trust has no third-party crate and cannot verify signatures; it refuses unsigned 27.2 Planned removals # syn from the strict feature Today strict implies syntax-rust ; a minimal feature set MUST NOT (structural Rust extractor with precision.parser = dctx-structural/1 ) serde , serde_json , thiserror , production sha2 The facade's hand-written canonical JSON; std Error ; dctx-hash rusqlite and bundled SQLite syn stack from the default build Held-out precision ≥ syn − 1 point; zero wrong exact edges Kept as a disclosed, target-specific adapter dependency outside the minimal closure (plugins unavailable in that build), or a reviewed first-party syscall boundary in dctx-plugin-platform Confinement property tests; written unsafe review 27.3 Maintenance # dctx is Apache-2.0 open source, including the desktop app, with no license fee. Organizations that depend on dctx can sign a maintenance agreement for security response targets, long-term support and priority work; see MAINTENANCE.md . Build-closure targets are engineering goals. 28. Conformance suite # Verb goldens ( docs/design/contracts/GOLDEN-REQUESTS-v1.json ) The isolated, pinned protocol in docs/research/trail-code-2026-10/ (seven corpora and one adversarial, 140 targets, 70 questions, stability, freshness, adversarial, network audit). Rerun at every phase gate; numbers in §31.0 29. Formal models # TLA+ models with mutation witnesses cover the cache lifecycle ( docs/formal/dctx-cache ) and the plugin host ( docs/formal/dctx-plugins ). New models are required for the policy 30. Versioning and compatibility # 31.0 Measured baseline # dctx 17dff0b ( dctx-cli v0.25.0 development line) against Trail-Code 0.23.1 on full method, raw data and scripts in docs/research/trail-code-2026-10/ . Every gate in report §7, data/accuracy.csv Definition ranked first ( find against ask ) Warm find : small and medium corpora / largest corpus (core) 0.69–1.40 s / 1.65 s ( callers 0.83 s) 158 MB -> 946 MB; gc --dry-run reclaimed 0 bytes Historical: 0 of 63 ( 17dff0b ); 2026-11-06: 33 of 33 ( 0495f5f , three pinned local corpora, unrelated comment edits); JSON 33 of 33, also identical over five runs; paired-answer M7 = 1.0 Historical: data/stability.csv ; new CSV , protocol and limits 405,601,700 bytes of node_modules plus Node .gitignore modified and .ignore added on every build Gitignored secret with no .git present Non-ignored .env in pack / build printed by pack 31.1 Phases # because they touch crates/dctx-template , manifests and CI, not the index. P0 Close the holes (§4 item 3, §7, §11) neighbors --edge calls --dir in non-empty on ≥ 120 of 140 targets; precision ( exact ∪ name ) ≥ 0.95; recall ≥ 0.88 on rare (comparison 0.93), ≥ 0.81 on collision (0.86), ≥ 0.35 on hub (0.42), ≥ 0.25 on receiver (0.56); zero wrong exact . Text answers identical after an unrelated edit ≥ 95 % (0 of 63); JSON identical over 5 runs. Task score ≥ 95 of 140 (69). The adversarial .env value absent from pack output; path listed P1 Answer the questions agents ask (§8, §10) Bounded overview for map without a target, p: and directory targets; grep ; find tokenization; small budgets degrade; omission counts in precision P2 Persistent incremental index (§18–20) Per-file fact segments keyed by FactKey ; content-addressed generations; superseded same-root generations reclaimed at the next invocation; two-level freshness; lazy per-section loads; parallel cold build; per-file fact cap; status First query after a one-line edit ≤ 2× warm on every corpus (core 7.48 s -> ≤ 3.0 s; django 2.70 s -> ≤ 1.7 s); cache per root ≤ 1.5× one generation after 10 edits (946 MB -> ≤ 240 MB); gc reclaims superseded bytes; warm queries on core ≤ 0.8 s and ≤ 150 MiB (1.45 s / 370 MiB; comparison 0.83 s); cold core ≤ 5 s / ≤ 150 MiB (6.05 s / 567 MiB); cold time ≤ 0.5× comparison on every corpus; status ≤ 50 ms P3 Binder (§7.1) dctx-map-bind : scope graph, per-language import resolution from lexed manifests, receiver-type rules, typed rung, edge corpus Receiver recall ≥ 0.56, interface name-level ≥ 0.42, hub ≥ 0.42; exact ∪ typed precision ≥ 0.95; zero wrong exact ; callees question ≥ 10 of 14 (2) P4 Token economics (§12) Tiers T0–T3, view digests, --since deltas, session dedup, compression levels, planner, dctx bench tokens , agent seeding E1 Organization control (§14–17; parallel) POLICY / TENANT , seven layers, .dctxpol , enrollment, explain, receipts E2 Minimal build profile (§27; parallel) Removals in §27.2; docs/DEPENDENCIES.md with CI diff; truthful --version ; version strings matching the actual release or development version cargo tree -e normal for a minimal feature set lists only dctx-* crates and the Ed25519 verifier closure behind trust ; the strict feature no longer implies syn P5 Surfaces (§24–26) Agent hooks, blast , learnings and check , vcs.changes Hooks idempotent with receipts; blast ≤ 100 ms warm P6 Overlays and D3 (§23.2, §27.2) LSP and SCIP overlays; network capability; CI comment plugin; first-party Rust structural extractor replaces syn in the default build Overlays never alter first-party facts; PP1–PP10 still modeled; syn removed only at corpus parity 32. Non-goals # Appendix A — Lineage # dircontxt , pure C (v1.0.0, 15.11.2025; legacy-c/ ) Give a model the whole project without pasting forty files: one structured .llmcontext.txt , a binary state file, version-aware snapshots and diffs, a three-tier ignore hierarchy, global configuration. Zero dependencies. dctx , Rust dctx 1.0 (this specification) Appendix B — Comparison with Trail-Code # docs/research/trail-code-2026-10/REPORT.md . One Rust binary; std-only core; zero third-party crates in the tagged 0.25.0 dctx-core /CLI; 46 in the development line (§27) Telemetry on by default (opt-out); daily update check not gated by the opt-out; writes .gitignore / .ignore on every build Lexers and resolver landed; edges not emitted by the shipped CLI (P0); typed rung planned (§7.1) Appendix C — Reserved names # Id prefixes m: , s: , d: , k: , p: , @ ; DTS section kinds 16–31; plugin namespace dctx/ ; file names .dctx/ , .dctxignore , .dctxpol ; environment variables DCTX_* . Appendix D — Document map # docs/design/PLUGINS.md , docs/design/plugin-api/ --- url: https://www.dctx.internet.technology/docs/privacy/ title: Privacy guarantees source: https://github.com/Eris-Margeta/dctx/blob/main/docs/ADR-014-Privacy-Guarantees-and-Ignore-Semantics.md --- Document: `docs/ADR-014-Privacy-Guarantees-and-Ignore-Semantics.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/privacy/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt ADR-014: Privacy Guarantees & Ignore Semantics View source · Edit on GitHub · Markdown · docs/ADR-014-Privacy-Guarantees-and-Ignore-Semantics.md · 2,817 words · updated 13 November 2026 On this page Context and Problem Statement Decision Drivers Considered Options Decision Outcome Rule System Definition Semantic Definitions Privacy Guarantees (Formal) Performance Characteristics Implementation (COMPLETED) Consequences Compliance & Validation Related Decisions References Implementation Work Orders Test Coverage Summary Status: current — architectural principle retained; historical examples describe their original release. For shipped behavior and limitations, see the README , testing guide and specification . Earlier “formally proven” wording refers to historical tests; tests and defense layers do not constitute a formal proof of all implementations. Date: 2026-02-02 Approved: 2026-02-02 Implemented: 2026-02-02 (WO-050 through WO-054) Deciders: Operator, AI Assistant Context: Phase 10.6 - Safety-Critical Privacy & Performance Audit Context and Problem Statement # Users trust dctx with their entire codebases, including sensitive files like .env , .git/ , API keys, credentials, and proprietary source code. Our ignore and omit systems were implemented primarily for output cleanliness and token efficiency, but we have not formally guaranteed that ignored files are NEVER read into memory. 1. Are ignored files ( .env , credentials) ever read into memory? 2. Does the --debug-ignored flag compromise privacy? Risk: Without formal privacy guarantees, users cannot trust dctx with sensitive codebases. A single accidental file read could expose credentials, leak proprietary code, or violate security policies. Decision Drivers # Privacy First: Ignored files must NEVER be read, regardless of flags or configuration Performance: Ignored folders must be skipped entirely (no recursion) Semantic Clarity: IGNORE vs OMIT must have clear, enforced meanings Debug Transparency: Users must be able to verify their ignore rules work correctly Template Safety: Custom templates must not accidentally trigger I/O on ignored files Zero Trust: Assume users handle classified/sensitive information Option 1: Status Quo (No Formal Guarantees) # Pro: No code changes required Pro: Current behavior is already safe (but undocumented) Con: No formal verification or tests Con: Users cannot trust the system Con: Template variables could be unsafe in the future Verdict: [no] Rejected - Privacy must be provable, not assumed Option 2: Full Privacy Audit + Formal Guarantees (SELECTED) # Pro: Provable privacy through code analysis and tests Pro: Clear semantic distinction between IGNORE and OMIT Pro: Template variable safety system prevents accidental reads Pro: Performance optimizations (skip ignored folders) Pro: Debug mode that doesn't compromise privacy Con: Requires implementation work (2-3 hours) Verdict: [yes] SELECTED - Only acceptable solution for sensitive codebases Option 3: Encryption-Based Approach # Pro: Could encrypt ignored file contents in memory Con: Massive complexity, performance overhead Con: Doesn't solve the problem (still reading files) Verdict: [no] Rejected - Overengineered, doesn't address root issue Decision Outcome # Chosen Option: Option 2 - Full Privacy Audit + Formal Guarantees Rule System Definition # IGNORE (default) [no] NEVER IGNORE ( --debug-ignored ) [yes] Shown with [IGNORED] marker [no] NEVER OMIT (always) [warning] [Content omitted by pattern rules] [no] NEVER IGNORE # Meaning: "This file/folder does not exist for our purposes." - .git/ - Version control internals - node_modules/ , target/ , __pycache__/ - Build artifacts - .env , .secrets - Credentials and sensitive configuration - *.log , *.tmp - Temporary files - Debug Mode: Visible in tree with [IGNORED] marker, folder recursed, but files never read - Configuration: .dctxignore (project) or ~/.config/dctx/ignore (global) OMIT # Meaning: "This file exists and is relevant to the project structure, but we don't care about its contents." - package-lock.json , Cargo.lock - Lockfiles (structure matters, content doesn't) - *.svg - Image files (relevant to project, but binary/verbose) - go.sum , yarn.lock - Dependency checksums - Content section shows: [Content omitted by pattern rules] Debug Mode ( --debug-ignored ) # Purpose: Allow users to verify their ignore rules are working correctly. - Shows ignored files/folders in directory tree with [IGNORED] marker - CRITICAL: Files are still NEVER read into memory - Grayed-out metadata: SIZE from stat() only, never from content reading SENSITIVE (strict deny, v1) # Meaning: "This file holds credentials. No dctx command ever reads, hashes, indexes or prints its bytes." Shapes (final path component, ASCII case-insensitive; the single list is dctx_core::filter::is_secret_shaped_name ): - env files: .env , .env.* , *.env , .envrc - keys, certificates and keystores: *.pem , *.key , *.p12 , *.pfx , *.jks , *.keystore - SSH private keys: id_rsa , id_dsa , id_ecdsa , id_ed25519 , and those names with a _ / - suffix without a dot ( id_rsa_deploy ); id_rsa.pub is not matched - credentials: credentials , credentials.<data> , *.credentials.json , secrets.<data> (data = json , yaml , yml , toml , ini , xml ); credentials.py and secrets.rs stay ordinary source - token files: .netrc , _netrc , .npmrc , .pypirc , .pgpass , .htpasswd , .git-credentials - Applies whether or not the file is git-tracked, to every surface: pack (all view filters, including --include , --ext , --hidden and --debug-ignored ), every dctx map verb (map, find, read, explain, skeleton, grep, neighbors, hubs, path, export; by stable id or by raw path; with or without --in ). - Enforced in the map policy ( PolicyView::decide ), again before any map read ( Session::read_verified ), in map grep, in the pack scan ( dctx-pack snapshot) and in the dctx-map-query source adapter. - No override. v1 has no --allow-sensitive flag, and repository or global rule files cannot Verification: crates/dctx/tests/map_sensitive_files.rs , the unit tests next to is_secret_shaped_name , PolicyView::decide and the pack scan, and the end-to-end check <repo>/scripts/checks/V1-1.zsh (a git-tracked fixture with one canary per shape, run against every command). .git (hard guard, v1) # Any path with a .git segment, at any depth, is excluded by PolicyView::decide before the rule layers are consulted, so !.git/ , !.g*/ or !nested/.git/** in .gitignore or .dctxignore cannot re-include it: the map verbs never list or read it, and Session::read_verified refuses it too. pack excludes it as well ( dctx-pack snapshot); only --debug-ignored still lists it by name, never reading it. Tests: git_negations_never_list_or_read_git in crates/dctx/tests/git_and_symlink_privacy.rs and in the pack snapshot. Symlinks (v1) # dctx::FsSource never follows a symlink: a symlinked final component is refused before the open, and the open itself uses O_NOFOLLOW (raw platform values; crates/dctx has no libc dependency), so a symlink swapped in after refused for listings and reads. Tests: crates/dctx/src/adapters/fs.rs and crates/dctx/tests/git_and_symlink_privacy.rs . DCTX_INDEX_IGNORED=1 # This environment switch (dctx-cli host::project_rules ) makes pack and the map verbs ignore every ignore file (global ignore, .gitignore , nested .gitignore , .dctxignore ); omit files and the built-in rules still load. It does not touch the SENSITIVE deny, the .git guard or the symlink rules above: those do not come from rule files. <repo>/scripts/checks/V1-1.zsh reruns its canary checks with the switch set. Guarantee 1: Ignored Files Never Enter Read Queue [yes] # Assertion: Files matching ignore rules are excluded at tree construction time ( walker.rs:136-146 ) via should_ignore_item() check. They never appear in the DirContextTreeNode tree, therefore never collected by collect_file_paths() , therefore never read by populate_file_contents_parallel() . Verification: [yes] PROVEN - [yes] Unit test: test_collect_file_paths_skips_ignored - ignored file never in read queue - [yes] Unit test: test_collect_file_paths_skips_ignored_subtree - entire subtrees skipped Guarantee 2: Ignored Folders Skip Recursion # Assertion: When a folder matches ignore rules, walk_recursive() uses continue (walker.rs:146) to skip the item entirely. The function is never called recursively on that folder's children. - Performance benchmark: 500MB node_modules/ should take < 100ms to skip Guarantee 3: Debug Mode Does Not Compromise Privacy [yes] # Assertion: When --debug-ignored is active, the system recurses into ignored folders and shows them in the tree, but the files are marked with is_ignored: true flag. The populate_file_contents_parallel() function respects this flag and never calls fs::read() on ignored files. Verification: [yes] PROVEN - [yes] Test: test_ignored_files_shown_with_marker - .env appears in tree with [IGNORED] - [yes] Test: test_ignored_files_never_have_content - no content blocks for ignored files - [yes] Test: test_collect_file_paths_skips_ignored - ignored files never enter read queue Guarantee 4: Template Variables Cannot Trigger Unsafe Reads [yes] # Assertion: Template variables are classified by I/O requirement: - Metadata-Only: {{{file_id}}} , {{{file_path}}} , {{{file_size}}} , {{{mod}}} (safe - from stat() ) - Content-Requiring: {{{lines}}} , {{{content_preview}}} (unsafe - requires fs::read() ) For ignored/omitted files, content-requiring variables are never resolved due to !node.is_ignored guard preventing content block rendering. Verification: [yes] PROVEN - [yes] Test: test_template_variable_safety_for_ignored_files with 6 comprehensive assertions (WO-054) Ignored Folder Skip (Primary Optimization) # Scenario: Project with 500MB node_modules/ (50,000 files) fs::read() Calls Performance Gain: 50-100x faster for large ignored folders. Omit Pattern Performance # Scenario: Lockfiles in monorepo (20 files, 10MB each) Performance Gain: 20x faster, 100x less memory. Phase 1: Data Structure Changes [yes] (WO-050) # Completed: 2026-02-02 [yes] Added is_ignored: bool to DirContextTreeNode struct (datatypes.rs:15) [yes] Default: false (only set to true in debug mode) Code Location: crates/dctx-core/src/datatypes.rs:15 Phase 2: Walker Logic Enhancement [yes] (WO-051) # Completed: 2026-02-02 [yes] walk_directory_structure() and walk_recursive() accept debug_ignored: bool parameter [yes] Default behavior: Skip ignored items with continue (current behavior preserved) [yes] Debug behavior: Recurse into ignored folders, mark all nodes with is_ignored: true [yes] Added mark_subtree_as_ignored() helper function for recursive flag propagation - crates/dctx-core/src/walker.rs:95-150 - Enhanced walk_recursive() - crates/dctx-core/src/walker.rs:mark_subtree_as_ignored() - Helper function - crates/dctx-cli/src/main.rs - CLI integration Phase 3: Privacy Enforcement in Collection [yes] (WO-052) # Completed: 2026-02-02 [yes] Updated collect_file_paths() to respect is_ignored flag and skip ignored files [yes] Added test_collect_file_paths_skips_ignored - proves ignored files never collected [yes] Added test_collect_file_paths_skips_ignored_subtree - proves entire subtrees skipped - crates/dctx-core/src/walker.rs:180 - Collection filter - crates/dctx-core/src/walker.rs::test_collect_file_paths_skips_ignored - Privacy test 1 - crates/dctx-core/src/walker.rs::test_collect_file_paths_skips_ignored_subtree - Privacy test 2 Phase 4: Formatter Respect for is_ignored Flag [yes] (WO-053) # Completed: 2026-02-02 [yes] Directory tree rendering: Append [IGNORED] marker to ignored items [yes] Content section: Skip ignored items via !node.is_ignored guard (llm_formatter.rs:345) [yes] Diff section: Skip ignored items via !node.is_ignored guard (llm_formatter.rs:389) - crates/dctx-core/src/llm_formatter.rs:345 - Content block guard - crates/dctx-core/src/llm_formatter.rs:389 - Diff block guard - crates/dctx-core/src/llm_formatter.rs::test_ignored_files_shown_with_marker - crates/dctx-core/src/llm_formatter.rs::test_ignored_files_never_have_content - crates/dctx-core/src/llm_formatter.rs::test_ignored_files_never_in_diff Phase 5: Template Variable Safety System [yes] (WO-054) # Completed: 2026-02-02 [yes] Created test_template_variable_safety_for_ignored_files with 6 comprehensive assertions - crates/dctx-core/src/llm_formatter.rs - Module-level safety documentation - crates/dctx-core/src/llm_formatter.rs:345 - Safety comment at guard - crates/dctx-core/src/llm_formatter.rs::test_template_variable_safety_for_ignored_files - docs/guides/DEVELOPER-GUIDE.md - Template Variable Safety section Positive # [yes] Provable Privacy: Users can verify ignored files are never read [yes] Performance Boost: 50-100x faster for projects with large ignored folders [yes] Semantic Clarity: IGNORE vs OMIT distinction is clear and enforced [yes] Debug Transparency: Users can verify ignore rules without compromising privacy [yes] Template Safety: Custom templates cannot accidentally leak ignored file contents [yes] Trust: Enterprise users can confidently use dctx on classified codebases Neutral # [settings] Implementation Cost: 2-3 hours of development work [settings] Test Overhead: 4 new privacy tests, 2 performance benchmarks [settings] Documentation: ADR, README security section, developer guide updates Negative # [no] API Change: walk_recursive() signature changes (internal API only) [no] Binary Size: +1-2KB for additional logic (negligible) [no] Complexity: Template variable classification system adds minor complexity Privacy Compliance Checklist [yes] ALL COMPLETE # [yes] Ignored files never appear in DirContextTreeNode tree (default mode) - WO-051 [yes] fs::read() never called on ignored files - Proven via test chain WO-052 [yes] Template variables respect is_ignored flag - WO-054 Performance Validation Checklist # Documentation Checklist (IN PROGRESS - WO-055 through WO-059) # [pending] CLI --help documents --debug-ignored behavior (WO-056 - PENDING) Related Decisions # ADR-008: Content Omission Pattern System (established omit rules) ADR-009: Binary File Detection and Content Omission (binary classification) ADR-001: System Architecture (centralized state management) ADR-011: Advanced CLI Filters (filter system that respects privacy) References # Walker implementation: crates/dctx-core/src/walker.rs Ignore rules: crates/dctx-core/src/ignore.rs Omit rules: crates/dctx-core/src/omit_content.rs Formatter: crates/dctx-core/src/llm_formatter.rs Phase 10.6 specification: the archived PROJECT-DEVELOPMENT-ELABORATION.md in docs/LEGACY/ Implementation Work Orders # Current Status: Core implementation complete. Documentation updates in progress. Test Coverage Summary # Total Tests: 290 (as of WO-054) Integration Tests: 5/5 passing (Phase 5 test-integrity.sh) 1. [yes] test_collect_file_paths_skips_ignored - Single ignored file never collected 2. [yes] test_collect_file_paths_skips_ignored_subtree - Entire ignored subtree skipped 3. [yes] test_ignored_files_shown_with_marker - Debug mode shows [IGNORED] marker 4. [yes] test_ignored_files_never_have_content - No content blocks for ignored files 5. [yes] test_ignored_files_never_in_diff - No diff blocks for ignored files 6. [yes] test_template_variable_safety_for_ignored_files - Template safety with 6 assertions Privacy Guarantee Status: [yes] FORMALLY PROVEN through test chain and multi-layer defense --- url: https://www.dctx.internet.technology/docs/language-coverage/ title: Language coverage (ADR-018) source: https://github.com/Eris-Margeta/dctx/blob/main/docs/ADR-018-Language-Coverage.md --- Document: `docs/ADR-018-Language-Coverage.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/language-coverage/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt ADR-018: Language Coverage View source · Edit on GitHub · Markdown · docs/ADR-018-Language-Coverage.md · 516 words · updated 7 November 2026 On this page Context Decision Implementation Results Trade-offs Alternatives Considered References Lessons Learned Future Work Status: superseded — historical design and implementation record. The original 13-family scope below is superseded by the current language registry table ; confidence and completion principles remain relevant. The Problem # Map facts need explicit coverage and completion claims across source/configuration languages; precision is separate from edge confidence ( crates/dctx-map-model/src/domain/precision.rs ). Root Cause Analysis # Structural extraction is not a full grammar claim, and incomplete extraction must not silently become complete facts ( crates/dctx-map-model/src/domain/precision.rs , crates/dctx-map-parse/src/adapters/mod.rs ). Decision # Use pure structural extraction for 13 families: Rust, JavaScript/TypeScript, Markdown, Python, Go, Java, C/C++, configuration (JSON/TOML/YAML), C#, Kotlin, Ruby, PHP and Swift ( crates/dctx/src/index/extract.rs , docs/CRATE-MAP.md ). The facade's default profile uses hand-written extraction, including line-oriented Rust and the first-party Markdown extractor. Qualification: dctx-lex-rust itself uses syn ; it is optional behind facade syntax-rust , so “13 hand-written lexers” is not a claim about every lexer crate or map-parse Rust implementation ( crates/dctx/src/index/extract.rs , crates/dctx/Cargo.toml , crates/dctx-lex-rust/src/lib.rs ). Keep one shared facade dispatch and fact-to-symbol conversion in crates/dctx/src/index/lex_dispatch.rs ; Rust and Markdown retain specialized entry paths in crates/dctx/src/index/extract.rs . Carry coverage ( syntax , structural , opaque ), completion ( complete , partial , refused ) and bounded parser identity separately from confidence ( crates/dctx-map-model/src/domain/precision.rs ). Phase 1: Pure Lexers and Facade Projection # The shared dispatch converts nodes without reading source or retaining bodies. New language branches expose only complete extraction; JavaScript/TypeScript preserve their existing partial-fact projection ( crates/dctx/src/index/lex_dispatch.rs ). The facade rejects NUL/non-UTF-8 symbol extraction and assigns stable ids and containment after extraction ( crates/dctx/src/index/extract.rs ). Phase 2: Map-parse Adapters # PureParser dispatches the language adapters over caller-provided bytes; partial/diagnostic extraction is refused as ParseError::Syntax , and unknown languages have a module-only fallback ( crates/dctx-map-parse/src/adapters/mod.rs ). Shared fact assembly records file precision and finalizes source-ordered facts with duplicate-id handling ( crates/dctx-map-parse/src/adapters/facts.rs ). Phase 3: Store Invariants Gate # The parser gate checks file ownership, unique/kind-correct ids, source-bounded spans, valid confidence/kind combinations, existing edge endpoints and containment reachability. It also simulates query insertion of Place/Package nodes to catch duplicate ids ( crates/dctx-map-parse/tests/lexers.rs , crates/dctx-map-parse/tests/fuzz_all.rs ). Phase 4: Fuzz Gate # Seeded bounded property tests exercise arbitrary bytes, Unicode, malformed inputs, deterministic results, successful-result store invariants and fixture prefixes without executing source ( crates/dctx-map-parse/tests/fuzz_all.rs ). Results # The gate source defines successful fixture controls as well as refusal/robustness cases; this record asserts test obligations, not a new passing execution ( crates/dctx-map-parse/tests/lexers.rs , crates/dctx-map-parse/tests/fuzz_all.rs ). Benefits # Structural facts can be produced without a default tree-sitter runtime, with explicit precision and conservative abstention ( crates/dctx-map-parse/src/adapters/mod.rs , crates/dctx/src/index/lex_dispatch.rs ). Costs # The facade's structural Rust profile and optional syn path differ; the shared facade dispatch also deliberately differs from PureParser on JavaScript partial facts ( crates/dctx/src/index/extract.rs , crates/dctx/src/index/lex_dispatch.rs , crates/dctx-map-parse/src/adapters/mod.rs ). Alternatives Considered # The earlier spec proposed tree-sitter as the parser dependency. Current adapters retain it only behind syntax-tree-sitter as an optional oracle; languages without an included grammar use pure adapters even in that oracle ( docs/SPEC-MAP-MODE.md , crates/dctx-map-parse/src/adapters/mod.rs ). References # Inventory: docs/CRATE-MAP.md ; facade: crates/dctx/src/index/lex_dispatch.rs ; adapters: crates/dctx-map-parse/src/adapters/mod.rs ; robustness: crates/dctx-map-parse/tests/fuzz_all.rs . Lessons Learned # Language family count, structural coverage, grammar completeness and edge confidence are distinct claims; the Rust implementation qualification must remain visible ( docs/CRATE-MAP.md , crates/dctx-map-model/src/domain/precision.rs , crates/dctx-lex-rust/src/lib.rs ). Future Work # Keep tree-sitter optional and preserve precision/refusal and store-invariant gates when extending adapters; optional oracle coverage is limited to its included grammars ( crates/dctx-map-parse/src/adapters/mod.rs , crates/dctx-map-parse/tests/fuzz_all.rs ). --- url: https://www.dctx.internet.technology/docs/templates-contract/ title: Template contract (DTS v2) source: https://github.com/Eris-Margeta/dctx/blob/main/docs/design/contracts/DTS-v2.md --- Document: `docs/design/contracts/DTS-v2.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/templates-contract/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt DTS source v2 and compiled plan IR v1 View source · Edit on GitHub · Markdown · docs/design/contracts/DTS-v2.md · 648 words · updated 7 November 2026 On this page Compatibility and typed plan Permission and budgets Compiled IR envelope Owner tests and model Compatibility and typed plan # Available parser capability; Rust default syn ; optional native only explicit are normative. Custom source is built with explicit template build ; shipped compiled defaults need no runtime source parse. Template sources remain Permission and budgets # permission = host_grant ∩ organization_ceiling ∩ session_selection . capabilities; unreadable policy is PolicyUnavailable , never default-allow. Final-output token estimate is ceil(2 * UTF8_bytes / 7) over the complete Compiled IR envelope # IR magic DCTXIR\0\0 (8 bytes), major/minor u16, exact total length u64, sections. Each section has kind:u16, schema:u16, length:u32, payload[length] . Owner tests and model # clock/reordered-input equality. Model compile-> validated-plan-> authorized-view-> include a positive syn capability case and explicit optional tree-sitter case. --- url: https://www.dctx.internet.technology/docs/templating/ title: Templating engine (ADR-003) source: https://github.com/Eris-Margeta/dctx/blob/main/docs/ADR-003-Templating-Engine.md --- Document: `docs/ADR-003-Templating-Engine.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/templating/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt ADR-003: Extensible Templating System (DTS) & Compilation Strategy View source · Edit on GitHub · Markdown · docs/ADR-003-Templating-Engine.md · 508 words · updated 7 November 2026 On this page 1. Decision: Explicit Marker Definition 2. Decision: "Ahead-of-Time" (AOT) Template Compilation 3. Decision: Two-Pass Rendering Engine 4. Template File Structure 5. Available Data Variables (Runtime) Status: current — architectural principle retained; historical examples describe their original release. For shipped behavior and limitations, see the README , testing guide and specification . Date: 2026-01-08 Author: dctx Team Context: Users require granular control over the output format to support various AI models. The system must maintain high performance (avoiding expensive parsing on every run) and ensure robustness (instructions matching output). 1. Decision: Explicit Marker Definition # * start_marker_open (Default: < ) * start_marker_close (Default: > ) * end_marker_open (Default: </ ) * end_marker_close (Default: > ) This allows users to redefine tags completely, e.g., to [SECTION] ... [/SECTION] or {{#SECTION}} ... {{/SECTION}} . 2. Decision: "Ahead-of-Time" (AOT) Template Compilation # Parsing text templates, validating variable references, and checking for cycles is expensive. We will not do this during the standard dctx runtime. The "Baked-In" Default # The default template (defined in the ADR) is parsed at Rust Compile Time (or hardcoded as a static struct). This ensures dctx runs with zero parsing overhead out-of-the-box. User Custom Templates # Users can edit templates in ~/.config/dctx/templates/ . However, dctx does not read these text files directly during snapshot generation. * Action: User edits .dctx_template file. * Command: User runs dctx template build <path> . * Process: 1. dctx parses the text file. 3. Serializes the parsed structure into an optimized binary format (e.g., bincode ). 4. Saves the result to ~/.cache/dctx/templates/user_custom.bin . * Runtime: When dctx runs, if configured to use a custom template, it loads this pre-validated binary directly into memory. 3. Decision: Two-Pass Rendering Engine # Pass 1 (Config Resolution): Occurs during the "Template Build" phase. Resolves all {{VAR}} placeholders within the [VARIABLES] section. Pass 2 (Data Injection): Occurs during runtime. Injects {{{DATA}}} into the pre-compiled Partial structures ( [PARTIALS] section) and assembles the [LAYOUT] . 4. Template File Structure # 1. [VARIABLES]: Key-Value pairs for static strings. 2. [PARTIALS]: Definitions for repeated elements ( TREE_ENTRY , FILE_BLOCK ). 3. [LAYOUT]: The global document structure. 5. Available Data Variables (Runtime) # * {{{node.id}}} : Optimized incremental ID (e.g., 1, 2, 10). * {{{node.path}}} : Relative path. * {{{node.type_char}}} : [D] or [F] . * {{{node.mod}}} : Unix timestamp in milliseconds. Available to custom templates. The built-in default template does not print it since 1.0.1, because a timestamp changes on a bare touch and breaks the byte-stable prefix of the page; --tree-stamps=on selects the built-in stamped template (the 1.0.0 text, MOD: and SIZE: on every tree line, MOD in the instructions). The default entry also leaves out {{{node.size_part}}} , since a size changes on every ordinary edit; {{{node.size}}} and {{{node.size_part}}} stay available to custom templates. * {{{node.size}}} : File size in bytes. * {{{file.lines}}} : Line count of the file. * {{{file.content}}} : Actual file content. --- url: https://www.dctx.internet.technology/docs/crate-map/ title: Crate map source: https://github.com/Eris-Margeta/dctx/blob/main/docs/CRATE-MAP.md --- Document: `docs/CRATE-MAP.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/crate-map/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt Crate map View source · Edit on GitHub · Markdown · docs/CRATE-MAP.md · 1,899 words · updated 7 November 2026 On this page How to read the inventory Shipped CLI path (v1) Core, engines and adapters Lexers and structural extractors Plugin infrastructure, facade and surfaces Dependency picture: core toward consumers Language wiring Cross-cutting rules and evidence locations Validation commands 40 non-fixture Cargo packages: 36 under crates/ , one plugin, one desktop, and two standalone tools. Root Cargo.toml includes crates, plugins and desktop; each tool declares its own workspace. bindings/README.md describes planned How to read the inventory # external normal dependencies. none means std-only at that crate boundary; first-party only means no direct external normal dependency, not an assertion Resolved transitive dependencies and runtime behavior are unverified here. Source convention: for every row named X , purpose is taken from crates/X/src/lib.rs:1 (first six lines), and dependency names from crates/X/Cargo.toml [dependencies] . These two paths are the row's evidence. apps/dctx-desktop/README.md:3 ; its lib header has no purpose description. boundaries in docs/design/ARCHITECTURE-DECISIONS.md (DX-ARCH-01). Shipped CLI path (v1) # What the dctx binary ( crates/dctx-cli ) actually runs, as of v1. No refactor: the other crates stay in the workspace. Shipped: dctx-cli and the crates/dctx facade session (index, find, grep, callers, callees, neighbors, skeleton, hubs, pack, read), with dctx-core (selection), dctx-hash, dctx-ports, dctx-pack, dctx-template, dctx-adapter-cache, dctx-adapter-fs (compatibility IO), dctx-map-model (records and rendering) and the dctx-lex-* extractors. Request types only: dctx-map-query . The CLI imports Request , Verb , Direction , Format , AnswerBudget and EdgeKind ; its Index engine is never called. Internal or legacy (compiled as dependencies of dctx-map-query , not run by the CLI): the dctx-map-query Index engine, dctx-map-store , dctx-map-scan , dctx-map-resolve , dctx-map-segment , dctx-adapter-store ; dctx-map-parse likewise. docs/SPEC-MAP-MODE.md sections 6–8 and 10 describe this engine. Unstable (no stability promise in v1): dctx-plugin-host, dctx-plugin-platform, dctx-plugin-protocol, dctx-plugin-distribution and dctx-desktop-api. The default dctx-cli build enables the plugin runtime and the bundled Git plugin process; --no-default-features --features strict builds without them. Core, engines and adapters # serde, serde_json (optional wire-json , enabled by default) sha2, thiserror; optional: tree-sitter, tree-sitter-rust, tree-sitter-md, tree-sitter-javascript, tree-sitter-typescript ( syntax-tree-sitter ) rusqlite ( bundled ), thiserror, serde_json Lexers and structural extractors # dctx-map-model defaults to external JSON dependencies. Do not infer an Plugin infrastructure, facade and surfaces # dctx-plugin-git ( plugins/dctx-plugin-git/ ) dctx-desktop ( apps/dctx-desktop/src-tauri/ ) architecture-bench ( tools/architecture-bench/ ) plugin-index ( tools/plugin-index/ ) Tool purpose evidence: each tool's src/lib.rs:1 ; dependencies: its Cargo.toml. Plugin purpose evidence: plugins/dctx-plugin-git/src/lib.rs:1 . Desktop dependencies: apps/dctx-desktop/src-tauri/Cargo.toml . tauri-build is a desktop build dependency, outside the normal-dependency uses syntax-rust ; plugin runtime dependencies use plugin-runtime . Dependency picture: core toward consumers # Language wiring # crates/dctx-map-parse/src/domain/facts.rs:8 ( Language , for_path ). Dispatch: crates/dctx-map-parse/src/adapters/mod.rs:40 ( PureParser ). Adapter paths below are relative to crates/dctx-map-parse/src/adapters/ ; each file imports the named lexer. These are all 13 dctx-lex-* packages. The optional TreeSitterParser in adapters/mod.rs:74 uses grammars for Rust, Cross-cutting rules and evidence locations # No Git in the core: product contracts crates/dctx-map-query/tests/no_git.rs (source spawn audit, PATH trap and Privacy, selection before content: crates/dctx-adapter-fs/tests/privacy.rs crates/dctx-map-query/tests/source_privacy.rs checks secrets, ignored files, Pure domain boundary: crates/dctx-core/src/lib.rs:1 points to crates/dctx-core/tests/purity.rs , which checks every source module without a Plugin PP1–PP10: historical PP matrix maps tests, Legacy removal: The migration removed the core IO wrappers and their exports. legacy removal inventory remains the historical inventory; compatibility record maps retired families to retained tests. Validation commands # Use TESTING.md for the current commands, toolchains, matrix and exclusions. Desktop backend checks use tools/desktop-check.sh ; browser evidence uses bun run e2e from apps/dctx-desktop . A skipped desktop check does not --- url: https://www.dctx.internet.technology/docs/exit-codes/ title: CLI exit codes source: https://github.com/Eris-Margeta/dctx/blob/main/docs/CLI-EXIT-CODES.md --- Document: `docs/CLI-EXIT-CODES.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/exit-codes/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt CLI exit codes View source · Edit on GitHub · Markdown · docs/CLI-EXIT-CODES.md · 929 words · updated 13 November 2026 On this page Details Outside the contract Engine RPC dctx map , dctx pack , dctx context , dctx doctor , dctx rpc , dctx languages , dctx cache , dctx template , a bare dctx without a terminal, an unknown command and a non-UTF-8 argument follow one contract: including a directory named fixtures ; paths are relative to that root. dctx read is an alias for dctx map read , with the same flags and exit codes. a find page, including one with no hits; --help map read m:nope.py (an id not in the index); map read logo.png (a binary file); pack of a directory with no packable file an unknown command or flag; a missing target ( dctx context with no TARGET); --depth 9 ; an empty find query; a stale --cursor ; m:../outside ; a non-UTF-8 argument; cache purge without --root / --all or --yes ; a template that does not compile; a bare dctx whose stdin or stdout is not a terminal --place /no/such/dir ; a corrupt or busy cache; a source over DCTX_MAX_SOURCE_BYTES ; an --output file that cannot be written; template build /no/such/file (the message names the path) Every failure prints two lines on stderr: [no] Error: <what went wrong> (prefixed with the command, as map: … ), then hint: <what to do next> . No input should reach a Rust panic; crates/dctx-cli/tests/cli_errors.rs and <repo>/scripts/checks/V1-5.zsh run twelve bad inputs and assert the code, the message, the hint and the absence of panicked . Details # An id the index does not hold is a facade outcome ( gone ), not an error. dctx map prints the gone page on stdout, then exits 1 with the hint. An empty find or grep page is an answer and exits 0. Exit 1 is for a named target that is not there. A binary target is detected before the scan: a NUL byte in the first 8 KiB of the file named by map , skeleton , explain or read (path or m: id). neighbors and path still accept such a module, since source files can import it. dctx pack exits 1 only when no view filter is set ( --ext , --include , --exclude , --binary , --empty , --non-empty , --large , --small , --hidden , --debug-ignored ). A filter that matches nothing still prints an empty page and exits 0. The page (stdout) and the pack bytes=… status line (stderr) are printed before the exit-1 message. pack exit 3 covers source, scan, render and output failures. A reader that closes stdout early ( dctx pack . | head -1 ) ends the run with exit 0 and no message, as cat does; every other failure keeps its code. dctx pack --for <TEXT> exits 1 when no name in TEXT matched the index (the page is printed first), 2 for a bad flag or a --budget outside 100..100000 (or --budget without --for ), and 3 when PATH is not a directory or the index fails. A facade refusal of the query ( InvalidRequest , BudgetTooSmall , StaleContinuation , Stale , UnsupportedCapability , UnsupportedVersion ) is 2; PolicyDenied and PolicyUnavailable are 1; every other facade error, and every error of the snapshot build, is 3. The mapping is dctx_cli::exit::from_facade . map hubs , map path and map export report their facade errors as text: an unknown id end of map path is 1, anything else 3. dctx context with no TARGET is 2; dctx context --help prints usage and exits 0. A TARGET that names nothing prints its empty page, then exits 1. dctx cache exits 2 for a bad flag or value, a purge without --root PATH / --all or --yes , and a --max-bytes that would loosen the cap; 1 for a --root id the ledger does not hold; 3 when the cache directory, policy or ledger cannot be read or written (the message names the directory). dctx template exits 2 for a bad flag and for a template that does not compile, and 3 when the template, the --dir directory or the --output file cannot be read or written (the message names the path). --output never writes through a symbolic link and refuses a target that is not a regular file. dctx with no command opens the interactive menu only when stdin and stdout are terminals; otherwise it prints the short usage as a hint and exits 2. dctx doctor follows the contract; dctx rpc keeps exit 0 at end of input (see Engine RPC below). Outside the contract # dctx plugin … and dctx git … return the plugin host's own codes. Engine RPC # dctx rpc uses the same operation paths and numeric taxonomy over versioned NDJSON . Each reply carries engine_version the same codes and hints as dctx cache status . An error reply does not change the server's process exit pack --for TEXT --json now emits the facade's context JSON page; its text member contains the same budgeted context page as plain pack --for TEXT . --- url: https://www.dctx.internet.technology/docs/benchmark/ title: Measurement evidence source: https://github.com/Eris-Margeta/dctx/blob/main/docs/BENCHMARK-20261030.md --- Document: `docs/BENCHMARK-20261030.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/benchmark/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt dctx measurement: grep plus file reads first View source · Edit on GitHub · Markdown · docs/BENCHMARK-20261030.md · 4,180 words · updated 13 November 2026 On this page Grep plus file reads Secondary historical evidence: other-tool protocols Historical three-way summary Run 7: 140 of 140 (main 53f8b6b, 31 October, 06:20 UTC) Run 6 (main 82ec474, 31 October, 02:04 UTC) Latest: run 5 and task-level re-run 3 (main a906884, 30 October, 16:39 and 17:05 UTC) Task-level questions: the October protocol, re-run on 30 October Run 4: callers recall wave (main de06a3d, 30 October, 09:17 UTC) Run 3: all outline families with call edges, .env leak closed (main 9c578fa, 30 October, 08:02 UTC) Run 2: call edges for the outline tier (main 99da638, 30 October, 07:24 UTC) Tables (run 1) Method Not claimed Changes included in the October baseline Next Independent benchmark, 31.10.2026, run uncapped on the Linux benchmark host The baseline for choosing dctx is grep plus reading files . Count the whole Grep plus file reads # The 11 November whole-session benchmark measured grep plus reads against dctx CLI: CLI median total tokens -5.01 %; the pre-registered 25 % savings rule was not met. Secondary historical evidence: other-tool protocols # "tokens" in these tables mean estimated tool stdout tokens , calculated as ceil(stdout_bytes / 3.5) , never whole-session tokens. Task scores are fact and the harness are in research/bench-3way-20261030/ ; the current goals are in the specification . Where another tool wins, the tables say so. dctx : main at ac8408c (the following commit only changes CHANGELOG.md ), release build, sha256 82bd48760932305748a00d2b32901c667af948f602822b9816cc5c545de7ebbc . Baseline for "before" columns: main at 4660f6d , the state before this night's work. Trail-Code @trailhq/trail-code 0.28.0 from npm, trail build . (no --deep , no --lsp ). graphify graphifyy 0.9.97 from PyPI, LLM-free code path only ( extract --code-only , GRAPHIFY_BACKEND=none ). Its LLM pass over docs, PDFs and images was not run, and nothing here measures it. Historical three-way summary # Run 7: dctx 140 of 140, Trail-Code 122, graphify 96 , with dctx using 29.3k tokens against Trail-Code's 88.9k and graphify's 197k. See "Run 7" below. Run 5: dctx P 0.995 / R 0.851 (first page), R 0.968 following 5 pages. Run 1 below: dctx P 0.993 / R 0.461 (first page), P 0.995 / R 0.706 following up to 5 pages. Trail-Code P 0.986 / R 0.436, graphify P 0.989 / R 0.196. Per corpus, Trail-Code wins ripgrep and trailcode, and dctx wins flask and pocketbase. Before tonight dctx recall was 0. dctx fastest on all 6 corpora : 0.16–1.16 s against 1.17–58.3 s for Trail-Code and 4.5–59 s for graphify. Peak RSS 19–90 MB against 121–1,020 MB and 74–394 MB. dctx fastest on search, callers and skeleton everywhere: 44–226 ms against 0.98–1.9 s for Trail-Code and 0.38–1.4 s for graphify. graphify's overview is a 7 ms read of a pre-written file. dctx map hubs gives the smallest overview on 4 of 6 corpora (Trail-Code on trailcode and docs) (30–652 tokens; Trail-Code 18–2,538; graphify 3,827–11,591). graphify gives the smallest callers and skeleton answers. dctx's skeleton is the largest of the three on ripgrep (1,784 tokens). Before tonight dctx's only overview was a 0.45–2.6 M-token pack . dctx and Trail-Code tie. Both are byte-identical across runs, and after an unrelated edit only the overview changes. graphify changed find, skeleton and overview after update , and 1 of 6 ripgrep queries was not deterministic. dctx and graphify made 0 socket attempts in every variant. Trail-Code made 49 blocked connect attempts when DO_NOT_TRACK is unset, and 0 with it set. Symbols: dctx 10 of 10, Trail-Code 7, graphify 5. Call edges, run 3: dctx 10 of 10, Trail-Code 7, graphify 5 (run 1: dctx 0). dctx's new outline tier is symbols only, labelled guess . Terraform and SQL get symbols only from dctx. Privacy canary (git-tracked .env files) Run 3: clean for all three tools after sensitive-file read protection landed. In run 1, pack had stopped printing the canary, but explicit dctx map read m:.env still returned the file. Trail-Code and graphify leaked nothing in that run. Run 7: 140 of 140 (main 53f8b6b , 31 October, 06:20 UTC) # - unresolved-call output: neighbors --dir out also lists the calls the index cannot resolve, as calls:out:?<name> records after the resolved callees. These are receiver methods, builtins and external package calls. - dotted config keys: dotted config key matching ( dotted_key ), not yet wired into find . All landed checks passed together on the Linux benchmark host before the run. Raw results are in research/bench-3way-20261030/tasks/results/run5-53f8b6b/ and research/bench-3way-20261030/results/run7-53f8b6b/ . Task-level protocol (70 questions, 354 gold facts; generator, mapping and scorer unchanged): dctx 53f8b6b 140 (run 6: 136) 353 (342) Three-way run 7 : callers P / R on the first page 0.995 / 0.851 (all pages 0.968), the same as run 6. The language coverage table is unchanged at 10 of 10 with symbols and 9 of 10 with call edges; shell is still n . Its per-language edge counts rise (for example Scala 1 to 8) because the probe counts every calls record, and the new unresolved-call output includes the calls:out:? names. A count above zero says nothing new about resolved edges, so this run does not claim more resolved edges. Run 6 (main 82ec474 , 31 October, 02:04 UTC) # - declaration-definition pairing: a declaration-only symbol ( .mli , C/C++ header, .d.ts ) answers neighbors for its paired definition. - export-list extraction and outgoing-call extraction: export_list and out_calls , which are not yet wired into answers. All landed checks plus these four passed together on the Linux benchmark host before the run. Raw results are in research/bench-3way-20261030/results/run6-82ec474/ and research/bench-3way-20261030/tasks/results/run4-82ec474/ . Call-edge coverage on the mixed corpus: 9 of 10 (run 5: 8). OCaml now has edges through the .mli pairing. Shell still has none, because the probe samples bats @test blocks that call only external commands. Trail-Code has 7 and graphify 5. Task protocol: 136 / 140 , unchanged. Trail-Code has 122 and graphify 96. The 4 lost points are still callees questions; the next unresolved-call output improvement wires out_calls into neighbors. Latest: run 5 and task-level re-run 3 (main a906884 , 30 October, 16:39 and 17:05 UTC) # dctx a906884 adds four improvements on top of run 4. Caller-diversity improvements spread callers over files, makes bare calls skip methods, and ranks data-file keys below code. Declaration ranking puts exported declarations first in outlines, gives read sites for config keys, adds line numbers to find, and ranks exact-word concepts first. Caller paging orders callers by call-site count and fits pages to the budget. Language outline improvements add deeper Scala, Zig, Lua, Elixir and OCaml symbols. All 36 landed checks passed together on the Linux benchmark host before the run. The binary's sha256 starts with 76d8e9b59821 . Raw results are in research/bench-3way-20261030/results/run5-a906884/ and research/bench-3way-20261030/tasks/results/run3-a906884/ . Task-level protocol (70 questions, 354 gold facts; generator, mapping and scorer unchanged): dctx a906884 136 (re-run 2: 102) 342 (243) dctx now wins the task-level test. It scores 14 points more than Trail-Code with a third of Trail-Code's tokens. By question type, out of 14: dctx leads or ties on every type. The 4 points it still loses are all callees questions: ripgrep, pocketbase, django and core lose 1 each. In the three public corpora every missing fact is a call that the index could not resolve: a receiver method ( line_terminator , lookup_allowed ), a builtin ( callable ) or an external package ( Validate ). The core rows are sanitized. Unresolved-call reporting exposes these calls. Three-way run 5 (the same harness as runs 1-4): - Network: dctx and graphify made 0 attempts. Trail-Code made 1 blocked connect when DO_NOT_TRACK was unset. Call-edge coverage on the mixed corpus is 8 of 10 by the probe; Trail-Code has 7 and graphify 5. The probe samples the first 25 symbols of the six largest files per language. It now follows every skeleton page, so its symbol counts are comparable with Trail-Code's full listing. Two languages miss for reasons outside the call resolver: - OCaml: the first 25 symbols all come from cmdliner.mli , an interface file with no bodies. On cmdliner_arg.ml itself, str_of_pp lists 3 callers with their call lines. Declaration-definition pairing makes an interface declaration answer for its definition. - Shell: the first 25 symbols are bats @test blocks in test/bats.bats , which call external commands only. Task-level questions: the October protocol, re-run on 30 October # This is the same protocol as October: 70 questions over seven corpora, 354 gold facts, and October's generator and scorer. It uses no model, and an answer scores when the tool's raw output contains the gold facts. Commands, question mappings and deviations are in research/bench-3way-20261030/tasks/README.md . 122 (October: 122) 312 (312) dctx de06a3d , October mapping 25,929 (500,005) Trail-Code still wins the task-level test. dctx gained 8 points and needs a fifth of October's tokens, because its overview question now uses map hubs instead of the unbounded legacy tree. dctx's answers are the densest: 7.5 facts per 1,000 tokens against Trail-Code's 3.5. Where dctx still loses: - Caller facts need the call line, and neighbors returns the calling function's span. - A supplementary run that uses the verbs added since October reached 96 points ( map grep for config keys, map skeleton for outlines). It is not the October protocol, so it is not counted above. Task-level re-run 2 (dctx 5e1b12b , 30 October, 13:12 UTC) # dctx 5e1b12b adds call-site lines on caller records (call-site lines), the config-key literal fallback (config-key fallback) and multi-word concept ranking (concept ranking). Protocol, mapping and scorer are unchanged. The headline is in research/bench-3way-20261030/tasks/results/run2-5e1b12b/ . dctx 5e1b12b 102 (run 1: 77) Run 4: callers recall wave (main de06a3d , 30 October, 09:17 UTC) # The dctx binary's sha256 is 0a41481ffc6f9ecd5713be5af561bef9f1c13f980bfa69748d84540520b4086e . New since run 3: - compact neighbor records 42a3364 : compact neighbor records, so a page carries about 40 callers. - macro-argument calls 2812e28 : Rust calls inside macro arguments. - receiver calls baebc3a : receiver calls resolve to a lone method, and self-edges are listed in both directions. - brace, indent and ML outline improvements fff4f82 , 37db6a0 , aa681ea : deeper outline symbols. - cache ceilings de06a3d : per-root cache ceilings of 768 MiB. All 28 checks passed together before the run. Raw results are in research/bench-3way-20261030/results/run4-de06a3d/ . Call-edge coverage on the mixed corpus is 9 of 10 in this run. The brace outlines brace rewrite cost Zig its call edges on real code (the fixture still passes), which Zig call-edge repair is fixing. Trail-Code has 7 of 10 and graphify 5 of 10. The coverage table's symbol counts come from bounded map map pages. They are therefore not comparable with Trail-Code's full graph counts. Run 3: all outline families with call edges, .env leak closed (main 9c578fa , 30 October, 08:02 UTC) # The dctx binary's sha256 is 72c6a31f0ee807ddd8840c7d8b85c9d1652dcb1001b948fec9de8eabaf277d6d . New since run 2: - sensitive-file read protection 45a2c06 : map mode never reads env-shaped files. - ML and do/end call edges df6ab96 : Lua, Elixir, Julia, R, OCaml and Haskell calls. - Scala call edges 9c578fa : Scala spans and calls. - parser cache invalidation 8ac04e4 : parser id bump, so caches from before call edges are rebuilt. All 20 focused checks passed together on the Linux benchmark host before the run. Raw results are in research/bench-3way-20261030/results/run3-9c578fa/ . dctx: canary from a git-tracked .env in any output yes ( map read ) yes ( map read ) - Symbol depth in the outline tier: on the mixed corpus's 6 largest files per language, dctx finds 5–25 symbols per language. Trail-Code finds 83–2,559, because its tree-sitter grammars see every member. - Callers recall on ripgrep and trailcode: 0.25 and 0.33 against Trail-Code's 0.33 and 0.90. Run 2: call edges for the outline tier (main 99da638 , 30 October, 07:24 UTC) # Same harness, corpora and tool versions. The dctx binary's sha256 is 81b35b3eb5112921c4f773b2682c247ec667bfc3487ce0670aa5e3ec5a372d14 . The new commits are brace-family call edges ( 8859210 , brace family) and infrastructure call edges ( 99da638 , infra family). Raw results are in research/bench-3way-20261030/results/run2-99da638/ . 6 of 10 (Dart, Zig, Solidity, Terraform, SQL, shell) dctx is the only tool with call edges for Terraform and SQL. Scala still has none on real code, although the fixture passes; that is a follow-up. Lua, Elixir and OCaml call edges are still being implemented. Cold index (0.13–1.06 s), callers precision and recall, and the canary result are unchanged from run 1. The map read m:.env leak remains until sensitive-file read protection lands. Cold index (median wall s, peak RSS of the largest process, index size) # Callers accuracy (micro precision / recall, depth 1) # Warm latency and answer size (median ms, estimated tokens) # research/bench-3way-20261030/results/headline.md . Method # latencies are noisy. Every measured command ran as nice -n 10 taskset -c 24-31 unshare -Urn env -i … , with no network, scratch HOME and caches, and DO_NOT_TRACK=1 . One heavy process ran at a time. The network audit is a Corpora are pinned by SHA in research/bench-3way-20261030/corpora-shas.json : flask 3.1.3, ripgrep 15.2.0, Tokens are ceil(stdout_bytes / 3.5) for every tool. That is an estimate, not a tokenizer. The callers gold set is the regex oracle of the October protocol ( goldlib.py ) on 20 seeded targets per corpus. Query mapping: dctx map find / map neighbors --dir in --edge calls / map skeleton / map hubs . Trail-Code ask / callers / skeleton / map . graphify query / affected --relation calls / explain <file> / GRAPH_REPORT.md . Not claimed # Whole-session cost or task-level answer quality from these historical protocols. Historical fact scores describe raw tool outputs only; the 11 November study measures whole sessions with a frozen model. Changes included in the October baseline # Call and import edges ( 19e90a1 ), byte-stable answers ( ce18608 ), .env omission in pack ( 6d4deec ), outline symbols for 25 formats and plain-text sections ( 9c61ac9 , e0821e3 , 839bd45 , a32dad3 ), neighbors depth 4 ( 0de5ce1 ), hubs ( 6bc0cbc ), grep ( 5691234 ), skeleton ( 2243c38 ), path ( 670e9e3 ), export ( ac8408c ) and a 1 GiB source ceiling ( 5d26781 ). Each feature's focused check, and then all 15 checks together on ac8408c , passed on the Linux benchmark host before the benchmark ran. Next # Independent benchmark, 31.10.2026, run uncapped on the Linux benchmark host # Seeded selection of 3 repos the tools never saw (zoxide, requests, gin), gold from language servers and repo history, published regardless of outcome. Tasks: dctx 22/28 points, 31/36 facts, 6.85 facts per 1k tokens (Trail-Code 19/28, graphify 14/28). Callers against LSP gold, first page: dctx P 0.730 / R 0.341, Trail-Code P 0.731 / R 0.313, graphify P 0.920 / R 0.264. Honest read: dctx leads on task answers and token efficiency; caller recall on unseen repos is far below the in-house corpus (0.851), so the caller floors above hold only for the curated corpora. Full table and raw JSON: docs/research/bench-independent/results/20261031T191225Z/ . --- url: https://www.dctx.internet.technology/docs/stability/ title: Byte-stability report source: https://github.com/Eris-Margeta/dctx/blob/main/docs/research/stability-20261105/REPORT.md --- Document: `docs/research/stability-20261105/REPORT.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/stability/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt STAB-01: byte stability on 0495f5f View source · Edit on GitHub · Markdown · docs/research/stability-20261105/REPORT.md · 1,063 words · updated 7 November 2026 On this page Protocol and pins M7 and acceptance limits Exact commands and exits Measured 2026-11-06 UTC on Linux from commit 0495f5f87717df5385209d306b92328a8cd96cf6 . The directory retains its original evidence date. No engine changes were made. All 405 CLI invocations exited 0 , with empty stderr: 396 measurement invocations controls. All 33 default text headers were exactly # <place> <verb> ; all 33 default JSON answers omitted snapshot, generation and freshness.age_s . --meta --json controls confirmed that each corpus's snapshot changed after the edit. Protocol and pins # phase_query.py , with byte comparisons in aggregate.py , section 7. It runs data/stability.csv . The original /path/to/workdir/dctx-vs-trail host tree is absent. The repository contains the host's scripts/corpora.json . Checked alternate bench3 and perf-20261101 helper , rust/src/support.rs Add , tests/fixtures/basic.go render_answer_at , adapters/output.rs Each prefix is copied in full using git ls-tree -r --name-only <pin> -- <prefix> and git show <pin>:<path> , retaining paths relative to the prefix. Every file's size and SHA-256, and the CLI binary SHA-256, are in corpora.json . Work copies and isolated cache/config directories live in a disposable /tmp The original applicable map query shapes are retained: find --limit 10 , inbound neighbors --edge calls at depths 1 and 2, outbound neighbors, map --depth 2 --limit 40 , read , and explain . Each now runs in both formats. The current bounded skeleton , grep , hubs , and path verbs add four shapes per corpus, find --json --limit 40 , matching exact path and symbol. path tests a file's containment edge to that symbol. grep is confined to the target file. Default budgets and default output are used, without --meta in the measured after appending exactly \n// STAB-01 unrelated comment\n to the named unrelated search hits or hub counts. Original bytes are restored in a finally block and verified. Configuration and caches are isolated using XDG_CONFIG_HOME , XDG_CACHE_HOME and DCTX_CACHE_DIR ; inherited DCTX_* overrides are removed. helper and Add . Their empty answers are included. All three inbound-neighbor cases have records, all paths are found, and render_answer_at has nine returned followed. Whole-graph export has no unrelated graph input and is outside this M7 and acceptance limits # For each transition, M7 = longest common byte prefix of previous and current stdout / current stdout byte length. Both block lengths and the prefix length are stored in turn-prefixes.csv ; there are no empty blocks. tier-context M7 ≥ 0.9 gate. Tier layering remains target . No cross-platform, The three text read pages actually include their selected source bodies. Text explain still consists of header and id/kind/path, so §11's richer text-page Exact commands and exits # Run from /path/to/workdir/codex/STAB-01R : export PATH = $HOME/.cargo/bin:$PATH export CARGO_TARGET_DIR = $PWD/.target-stab cargo --offline build --locked -p dctx-cli > /tmp/stab-01-build.log 2 > & 1 Exit 101 : configured sccache failed with Operation not permitted , before compilation. A retry after unset RUSTC_WRAPPER , with output redirected to /tmp/stab-01-build-no-wrapper.log , also exited 101 : Cargo's user config still specified build.rustc-wrapper = "sccache" . export PATH = $HOME/.cargo/bin:$PATH export CARGO_TARGET_DIR = $PWD/.target-stab export RUSTC_WRAPPER = cargo --offline build --locked -p dctx-cli > /tmp/stab-01-build-direct.log 2 > & 1 python3 docs/research/stability-20261105/measure.py > /tmp/stab-01-measure.log 2 > & 1 Exits: build 0 ; measurement 0 ; independent raw-data audit 0 ; git diff --check 0 . Build logs and measurement.txt are preserved here. commands.md lists every query shape and setup/control command; runs.jsonl records all 405 exact argv arrays, shell-quoted byte counts and SHA-256 hashes. measure.py records a fresh run only when no runs.jsonl exists; use a fresh copy of the evidence directory to repeat it. stability.csv is the new measurement. The adjacent stability-original.csv is a byte-for-byte copy of the 46b54db2fb469dc4df70eaa0bf22b458a8089f437cdee3294efe071314280266 . --- url: https://www.dctx.internet.technology/docs/benchmark-oct/ title: Earlier two-way study source: https://github.com/Eris-Margeta/dctx/blob/main/docs/research/trail-code-2026-10/REPORT.md --- Document: `docs/research/trail-code-2026-10/REPORT.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/benchmark-oct/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt dctx vs Trail-Code: head-to-head benchmark (October 2026) View source · Edit on GitHub · Markdown · docs/research/trail-code-2026-10/REPORT.md · 7,229 words · updated 13 November 2026 On this page 1. Summary 2. Methodology 3. Footprint 4. Indexing (section 2 of the brief) 5. Query latency and output size (section 3 and 4) 6. Freshness and incremental updates (section 2) 7. Call-graph and definition accuracy (section 5) 8. Task-level information efficiency (section 6) 9. Cache-friendliness (section 7) 10. Robustness and privacy: adversarial corpus (section 10) 11. Network and telemetry audit 12. Files written by trail init (flask, -y) 13. Bounding (section 8) 14. Language coverage (section 9) 15. Where dctx wins / where Trail-Code wins / ties 16. Findings 17. Not tested, and deviations 18. Reproducing and one synthetic adversarial corpus. Every number below comes from data/raw/*.jsonl and can be regenerated with scripts/ . Where Trail-Code is better, this report says so plainly. dctx at commit 17dff0b454c24f43848abad1c88ea982e02731f7 (branch internal ), dctx-cli v0.25.0 , agent interface dctx map <map|find|neighbors|explain|read> . Trail-Code @trailhq/trail-code@0.23.1 from npm (repository HEAD b1211efd , whose package.json is also 0.23.1), CLI trail . 1. Summary # Trail-Code wins decisively. Trail precision 0.94 to 1.00, recall 0.10 to 0.96 per corpus. dctx returns no call or import edges at all (recall 0 on 140 targets): the CLI facade only emits contains edges. dctx wins. One 9.2 MB binary (libc, libm, libgcc_s) versus 405.6 MB of node_modules (8,567 files, 50 package versions) plus a Node runtime. dctx wins on all seven corpora: 0.09 to 6.05 s versus 2.44 to 94.9 s (2.8 to 69 times faster); peak RSS 8 to 567 MiB versus 181 to 2,111 MiB. Trail's index is smaller only on core (65 MB versus 158 MB). dctx wins on small and medium repos (30 to 260 ms versus 0.6 to 1.4 s; Node startup sets Trail's floor near 0.6 s). On the largest Rust corpus dctx re-reads a 158 MB generation per process (1.45 s, 370 MiB per query) and Trail's callers is faster (0.83 s). Tie on correctness : both see unstaged, untracked and staged edits and drop reverted symbols. Trail also adds the caller edge to the new function; dctx cannot. dctx's first query after an edit costs a full re-index (core: 7.5 s), and every edit adds a full new generation to the cache (core: 158 MB to 946 MB). Trail wins. Trail text outputs are byte-identical across runs and across unrelated edits. Every dctx answer starts with a header containing the snapshot digest, so any edit anywhere changes byte 21 to 50 of every answer; dctx JSON is never byte-identical twice ( age_s ). dctx wins for map verbs (hard 2,000-token cap, never exceeded; budgets below the minimum record size are refused with exit 1). Trail has no budget flag; single answers reached 142 KB (40.6k tokens). dctx's legacy tree and pack are unbounded (974 KB tree on django; 8.7 MB pack). dctx wins. Zero sockets in every audited dctx run and no writes to the repository in map mode. Trail does a daily npm version check that ignores DO_NOT_TRACK , records an install telemetry event in postinstall and tries to send it, and modifies .gitignore and adds .ignore on every trail build . dctx pack printed a fake .env secret; Trail never read .env . Host, isolation, contention # VM build-host : 32 vCPU Intel Xeon E5-2680 v2 @ 2.80 GHz, 94 GB RAM, Debian 13, kernel 6.12.111, Node v24.22.0, npm 11.19.1, rustc/cargo 1.99.0 ( data/env.txt ). taskset -c 24-31 (8 CPUs). The other batch was not pinned, so it could share those CPUs. (each row in data/raw/*runs.jsonl records load before and after; phases.jsonl records each phase). The ripgrep and pocketbase query phases ran at load 8 to 10, so treat their Trail find times Both tools ran as the dedicated unprivileged user dctxbench , with HOME , npm prefix, npm cache, XDG_CACHE_HOME and DCTX_CACHE_DIR inside /path/to/workdir/dctx-vs-trail , through scripts/benv ( env -i , then sudo -u dctxbench unshare -rn , then taskset ). After installs, clones and builds, DO_NOT_TRACK=1 (Trail's documented opt-out, dist/telemetry/gate.js ) was set for every measured Timing: GNU time 1.9 ( /usr/bin/time -v , 10 ms resolution) records wall, user+sys CPU and peak RSS for Output size: raw stdout bytes and ceil(bytes / 3.5) estimated tokens for both tools (identical to dctx's own ceil(2*bytes/7) ). This is an estimate, not a tokenizer. Builds and versions # dctx: source rsynced from the workstation (no target/ ), built with cargo build --release --locked -p dctx-cli -j 8 without a compiler cache: 98.7 s wall, 389 s user CPU. Binary: 9,207,072 bytes, sha256 26c3cb70...cbce . ldd : libgcc_s , libm , libc , ld-linux only. Trail-Code: npm install --save-exact @trailhq/trail-code@0.23.1 (39.96 s). npm 11.19 printed Trail's own postinstall and node-gyp builds; Node headers were downloaded into ~/.cache/node-gyp ). Corpora (pinned) # tag 3.1.3, 22d92470 tag 15.2.0, e89fff89 tag v0.40.5, 6f370ea7 tag 6.1.2, 2212534b core was copied without target/ and corpus/ ; its .agent/worktrees/ (copies of the tree) was also removed. Its raw outputs, symbol names, paths and source lines are redacted from data/ ( scripts/redact_private.py ); only numbers are published. Gold sets and scoring # Targets. scripts/select_targets.py picks 20 definitions per corpus with a fixed seed: 4 hubs scripts/goldlib.py , not either tool. Oracle. Comments and strings are blanked (a cross-line state machine for Rust and Go, per-line for JS/TS, triple-quote aware for Python). A line is a call site of N only if N is directly followed by an file or package, explicit import, self / this , Type:: ); receiver calls to names that also exist on standard-library types, and anything else unresolvable, are ambiguous and excluded from both in-repo definition of the name, plus self calls. Adjudication. A Trail calls hit is a true positive if its span contains a gold site of the target, listed in data/targets/*.targets.json ). The hand check found one oracle bug: a /* inside a Rust multi-line doc string started a fake block comment. After the fix the gold was rebuilt for the same targets ( scripts/regold.py ; one target changed, ripgrep unwrap_switch , 61 to 69 sites), and the ripgrep accuracy and task phases were rerun. The earlier rows are kept in data/raw/*.pre-regold . A remaining one true Trail hit (flask dumps ) count as a false positive. Tasks. scripts/phase_tasks.py builds 10 questions per corpus from the same oracle with fixed 3. Footprint # node_modules 405,601,700 bytes, 8,567 files 46 external crates in cargo tree -e normal (see TC-F11) 50 package versions (47 names) in npm ls --all ; largest: tree-sitter-wasm 128 MB, @trailhq/trail-code 129 MB (bundled grammars), tree-sitter-swift 73 MB, two LLM-provider SDKs 34 MB and 14 MB (used only by --deep ) postinstall records an anonymous install event and spawns a detached flush; ~/.graft/telemetry.json and ~/.graft/update-check.json created at install 4. Indexing (section 2 of the brief) # dctx map find main with an empty DCTX_CACHE_DIR . The Trail cold run is trail build . . No-op = repeat with nothing changed (dctx: same query; Trail: trail build . again and trail build --check . ). Trail --check s 0.09 (0.08) 0.45 (0.42) 0.72 (0.71) 0.31 (0.30) 2.42 (2.38) 2.48 (2.46) 6.05 (7.02) - core's dctx cost is dominated by configuration extraction. --profile on a cold run: parse/lex 3.39 s, - Trail's build --check (the CI freshness check) costs as much as a full build on pocketbase and django. - Trail writes its index into the repository: graft/ plus a modified .gitignore and a new .ignore on every corpus, or .trail/cache/ when the repo already has .trail/ (Trail's own repo). dctx map writes nothing into the repository and nothing into HOME (verified by full manifests before and after). 5. Query latency and output size (section 3 and 4) # find = dctx map find N --limit 10 / trail ask N ; callers = dctx map neighbors <id> --dir in --edge calls / trail callers N ; outline = dctx map map FILE --depth 2 --limit 40 / trail skeleton FILE ; read = dctx map read <id> --json / trail ask N --source --full -n 1 ; overview = legacy dctx . -t (the map verbs have no root overview, TC-F05) / trail map ; grep = none / trail grep 'N\(' . 0.83 / 1,366 0.81 / 1,196 dctx text mode is thin: find prints id kind path without line numbers, and read / explain in text mode print only the id line (152 to 247 bytes, no source and no signature). Source needs --json dctx --json repeats thirteen keys per record, many of them null . Under the same default budget a JSON find returned 4 records where the text find returned 10 (flask, dispatch_request ). pocketbase 0.72 s, trailcode 0.31 s ( data/queries_cold_dctx.csv ). Trail cannot answer without a graph ("no graph found ... run trail build first"), so its cold first answer is the cold build plus a query. Trail prepends a banner to callers , skeleton , grep , map and source answers. The banner estimates call, 6.3% of all Trail warm-query bytes and 54% of the callees answers. 6. Freshness and incremental updates (section 2) # file, then git add it, then revert everything ( data/freshness.csv ). snapshot. dctx cache status reported 473 MB reclaimable, and dctx cache gc --dry-run reclaimed 0 bytes ( blockers: unlink_grace ). Total dctx cache at the end of the run (all corpora including the 7. Call-graph and definition accuracy (section 5) # Interface/trait targets are scored at name level separately. Per-target rows: data/accuracy_targets.csv . Misses and false positives: data/raw/accuracy.jsonl (redacted for core). Find-def rank 1: dctx find / Trail ask Def in results: dctx / Trail ask dctx has no call graph in the shipped CLI. neighbors --edge calls returned empty on all 140 targets; --edge imports on module ids was also empty in spot checks (ripgrep, pocketbase). The lexers do extract references (for example EdgeKind::Calls in dctx-lex-* , dctx-map-parse/src/adapters/rust.rs ), but the facade index ( crates/dctx/src/index/extract.rs ) only emits contains edges, and dctx-map-resolve is linked only through dctx-map-query . Trail is precise but misses a lot on some corpora. Typical misses: Go methods called through variables (pocketbase Record.Verified , 0 of 39; Record.ValidatePassword , 0 of 36); Python methods called on module-level objects ( apps.get_app_configs() , 3 of 69); calls through a re-exported module name ( flask.abort(...) , 2 of 22); classmethods called on subclasses ( Index.as_view(...) , 0 of 20). Find definition: dctx find ranked the definition first more often (103/140 versus 79/140 for Trail ask ) and listed it in 139/140 first pages versus 109/140. Trail callers N also lists every 8. Task-level information efficiency (section 6) # data/targets/*.questions.json ; per-question rows: data/tasks.csv , data/tasks_by_question.csv . 105 / 500,005 / 69 of 140 / 169 of 354 70 / 88,691 / 122 of 140 / 312 of 354 7.15 / 4.98 no text search); concept search 0 / 12 (multi-word dctx map find returned no records); overview 14 / 13 (dctx through the unbounded legacy tree: 480k tokens over seven corpora versus 31.7k for trail map ). 9. Cache-friendliness (section 7) # directory ( data/stability.csv ). no : freshness.age_s changes every second no, every answer : header # <place> <verb> v1:sha256:<digest>:<bytes> g=<n> changes; common prefix 21 to 50 bytes yes for callers, callees, outline, grep, read, text find; map banner counts change; ask --json scores churn in the 9th to 16th digit none in map verbs; legacy dctx . prints the absolute path and a timing line ask --json includes absolute paths of .trail/learnings files age_s in JSON 10. Robustness and privacy: adversarial corpus (section 10) # scripts/gen_adversarial.py plants: a non-ignored .env with DCTXBENCH_FAKE_SECRET=sk-test-... , a gitignored directory and a gitignored *.secret.py with unique markers, an un-ignored node_modules/ , a NUL-containing .py , a 50 MB text file, a 5 MB single-line minified JS, a 5 MB generated Python module plain directory. Timeout 300 s per command ( data/raw/adversarial.jsonl ). none in map verbs or pack ; legacy dctx . -t exits 1 with resource limit exceeded: Depth > 128 not indexed, not in pack not indexed ( trail grep names the ignored paths in its footer) Gitignored files (no .git ) still excluded (rules read from .gitignore ) indexed : the gitignored secret value is in graft/.cache/extract.*.json and in trail grep sk-test output .env secret printed by dctx pack . (not in map answers or the map cache) node_modules/ (not ignored) NUL-containing .py 5 MB minified JS, 5 MB generated .py none (legacy dctx . writes .dctx/ ) .gitignore modified, .ignore added 11. Network and telemetry audit # strace -f -e trace=socket,connect,sendto,sendmsg,bind inside the network namespace ( data/raw/network.jsonl ). dctx map find , dctx pack . , dctx plugin list trail build . (telemetry on, and with DO_NOT_TRACK=1 ) trail callers with the daily update-check stamp expired, with and without DO_NOT_TRACK=1 resolves registry.npmjs.org through systemd-resolved's varlink socket (which works from inside a network namespace), then tries TCP 443 on 104.16.x.34 and 2606:4700::6810:x; connects fail with ENETUNREACH events are queued in ~/.graft/telemetry-queue.ndjson : app version, OS, arch, Node major, command, a random repo_id UUID, file-count bucket, languages, duration bucket npm install (network allowed) postinstall recorded an install event and spawned a detached flush ( flushedAt set in ~/.graft/telemetry.json ); delivery cannot be confirmed Trail's documented telemetry gates ( DO_NOT_TRACK , CI, trail telemetry disable ) did stop the usage 12. Files written by trail init (flask, -y ) # Repository (agent names replaced by <agent> ): .<agent>/settings.json , .<agent>/settings.local.json , .github/<agent>-instructions.md , .trail/.gitignore , .trail/README.md , .trail/hook.cjs , .trail/statusline.cjs , the index under .trail/cache/ (90 files). HOME (machine-wide): ~/.<agent>/settings.json (SessionStart, UserPromptSubmit, PostToolUse, Stop and SessionEnd hooks), ~/.<agent>/skills/trail/SKILL.md , ~/.<agent>/helpers/graft-hooks.cjs , ~/.trail/README.md , ~/.trail/install.json , ~/.trail/repos/index.json , ~/.trail/repos/known.json . --dry-run lists all of them first; --no-global skips the home directory. trail uninstall -y removed the repository wiring and the ~/.<agent> files, but left .trail/README.md , .trail/.gitignore and the four ~/.trail/ files behind. dctx has no init step. dctx map wrote nothing into the repositories or into HOME . 13. Bounding (section 8) # dctx map verbs: --budget 1..2000 (explain up to 1000) and --limit up to 40 are enforced. All 49 dctx outside map: dctx . -t wrote 974,082 bytes (278k tokens) for django and failed on the deep tree. dctx pack . printed 1.59 MB for flask and 8.67 MB for the adversarial corpus to stdout. Trail has no budget option. Largest single answers: skeleton of a 140 KB generated types.d.ts 142,197 bytes (40.6k tokens); ask --source --full -n 50 70,466 bytes; map --max-dirs 100000 53,870 bytes on core (9.9 s). grep is capped internally (15 to 22 KB even for grep e ), and ask -n 1000 14. Language coverage (section 9) # data/coverage.csv : Trail's numbers come from its full graph; dctx's from a seeded sample of up to 12 files per extension ( dctx map map FILE --depth 1 --limit 1 ). Source files: both tools give symbols to 83 to 100% of sampled .py , .rs , .go and .ts files (the rest are empty modules and __init__ -style files). Trail gave symbols to 2,010 of 2,919 django .py files, 1,283 of 1,420 core .rs , 450 of 457 pocketbase .go , 292 of 316 trailcode .ts . JavaScript: Trail indexed 16 of 111 django .js files and 177 of 251 pocketbase .js files (vendored Docs and config: dctx gives structure to .md , .json , .toml , .yaml and .yml (for example 12 of 12 sampled dctx .json and .toml ); Trail gives none. 15. Where dctx wins / where Trail-Code wins / ties # - Privacy: no sockets in any run; no repository or home writes in map mode; .gitignore honoured even without .git ; gitignored secrets never indexed. - Finding definitions: rank 1 in 103/140 cases versus 79/140 for trail ask . - Cheap no-op verification (0.04 to 1.34 s) versus trail build --check (2 to 86 s). - Text search ( trail grep , grouped by enclosing symbol) and a bounded repository map (1 to 15k tokens). - On the largest Rust corpus, warm callers and skeleton are faster than dctx (0.8 s versus 1.45 s) with - Neither follows symlink loops or escaping symlinks; both skip node_modules/ and non-UTF-8 file names; 16. Findings # Evidence: neighbors --edge calls empty for 140 of 140 targets across seven corpora ( data/accuracy.csv ); --edge imports empty on module ids in spot checks; Trail precision 0.94 to 1.00 and recall up to 0.96 on the same gold. callees and 6/14 on colliding names. The facade ( crates/dctx/src/index/extract.rs ) only emits contains edges, although the lexers already produce Calls / Imports references and dctx-map-resolve exists. Recommendation: wire reference facts from the lexers through dctx-map-resolve into the facade segment, with explicit confidence ( exact , name , guess ) on every edge and a record of dropped ambiguous instead of adding a type checker. Use scripts/phase_accuracy.py as the acceptance test. generations were byte-identical; cache gc --dry-run reclaimed 0 bytes ( unlink_grace ). Total cache Evidence: every map answer starts with # <place> <verb> v1:sha256:<digest>:<bytes> g=<n> , so any edit anywhere changes byte 21 to 50 of every answer ( data/stability.csv , 0 of 63 dctx answers unchanged after an unrelated edit versus 59 of 70 for Trail). JSON answers contain freshness.age_s , so no two JSON calls Evidence: dctx map read <id> and explain <id> in text mode print only the id line (152 to 247 bytes, no source, no signature); find text has no line numbers; JSON carries thirteen keys per record, often null , so a default-budget JSON find returned 4 records versus 10 in text. Recommendation: print source for read and the signature and summary for explain in text mode; add path:start-end to text records; drop null keys from JSON v2 (or add a compact JSON). Evidence: dctx map map p:<place> and k:<dir> answer gone , and directories are refused ("is a directory; pass a file path or a stable id"), although the guide says map outlines "the project root". The only overview is the legacy dctx . -t : 974 KB (278k tokens) on django, written into the repository as .dctx/<place>.llmcontext.txt , and it fails on trees deeper than 128. Trail's map answered in 1.7 to Recommendation: implement map p: and directory targets as a budgeted overview (directories, file counts, top symbols by in-degree once TC-F01 lands), paging through next , written to stdout only. Evidence: config-key questions scored 0/14 for dctx and 14/14 for Trail ( trail grep ). Recommendation: add a bounded dctx map grep verb in the core (pure Rust, same ignore rules, no Git), grouped by enclosing symbol id and capped by --budget with a continuation cursor. as opaque in the precision label, and load only the segment parts a query touches instead of the whole TC-F08 (major, privacy): dctx pack emits .env contents by default. Evidence: dctx pack . printed DCTXBENCH_FAKE_SECRET=sk-test-... from a non-gitignored .env ( data/raw/adversarial.jsonl , both variants). Map answers and the map cache did not contain it. Trail never read .env . Recommendation: ship a default sensitive-content omit list ( .env* , *.pem , *.key , id_* , credentials* , *.p12 ) that shows the path but never reads the content unless the user opts in. This Evidence: --budget 20 and JSON --budget 100 exit 1 ("budget too small: needs at least 336 bytes"). Recommendation: return the largest prefix that fits (ids only, then more / next ), or clamp to the floor 100 bytes, header only); Trail ask found the target in 6 of 7. Recommendation: split queries and identifiers on case and _ boundaries, rank by token overlap with names and first-line doc summaries (already present as summary ), all in the core without models. Evidence: cargo tree -p dctx-cli -e normal lists 46 external crates, including rusqlite with bundled SQLite C, ed25519-dalek , landlock , seccompiler , serde_json and syn 3, all compiled into the release build ( target/release/deps ). The binary itself only needs libc, libm and libgcc_s at run time. TC-F12 (minor, docs): docs/guides/MAP-MODE.md and --version --verbose are stale. Evidence: the guide says .gitignore rules are not loaded and --lines drops the start line; observed: gitignored files are excluded on the map path even without .git , and --lines 240-246 returned exactly lines 240 to 246. The guide says map outlines the project root (it does not, TC-F05) and that the default CLI extracts "conservative calls" (none are exposed, TC-F01). dctx --version --verbose lists languages: rust,javascript,typescript,markdown and parser dctx-lex-rust/syn-3.0.9 , while answers report dctx-structural/1 and Python, Go and others work. Recommendation: count omitted paths by reason in precision (for example omitted: {binary: 1, unnamed: 2} ) so an agent knows the map is incomplete. DO_NOT_TRACK and an install-time telemetry event; no repository writes versus .gitignore / .ignore to the user (~89 tokens per call, 54% of callees output). It is prompt steering inside tool output and it dctx cache status or a JSON field the caller can drop. Evidence: trail build --check 49.5 s on pocketbase and 86.5 s on django, the same as cold builds; TC-F18 (info): Trail indexes gitignored files when .git is absent. Evidence: in the no-git adversarial variant, Trail indexed ignored_dir/ and app.secret.py ; the fake secret value appeared in graft/.cache/extract.*.json and trail grep output. dctx excluded both. 17. Not tested, and deviations # Trail build --deep (needs an LLM key) and --lsp (no language servers installed on the host); trail blast , check , note , team , viz and the learnings features; Trail cloud workspaces. dctx plugins, TUI, templates and the optional syntax-rust build. Deviation: DO_NOT_TRACK was not set during npm install , so Trail's postinstall recorded an install scripts; the other corpora ran in one chained pass ( data/raw/phases.jsonl ). 18. Reproducing # On a Linux host with passwordless sudo: scripts/setup_host.sh (user, workspace, dctx build, pinned Trail install, pinned clones). Copy scripts/ to $BENCH_ROOT/scripts . scripts/run_all.sh runs every phase. Each phase script appends JSONL under $BENCH_ROOT/results . python3 scripts/aggregate.py RESULTS data/ regenerates data/*.csv and data/SUMMARY-TABLES.md . For a private corpus, run scripts/redact_private.py data/ <corpus> before publishing. Cleanup: sudo userdel -r dctxbench && sudo rm -rf /path/to/workdir && sudo apt-get remove -y time strace . Data index # data/env.txt , data/tool-help.txt host, versions, pins, binary hash, ldd , CLI help of both tools data/raw/runs.jsonl and *_runs.jsonl data/raw/accuracy.jsonl , tasks.jsonl , freshness.jsonl , bounding.jsonl , coverage*.jsonl , adversarial.jsonl , network.jsonl , init_writes.jsonl , writes.jsonl , index_size.jsonl data/*.csv , data/SUMMARY-TABLES.md --- url: https://www.dctx.internet.technology/docs/releasing/ title: Releasing source: https://github.com/Eris-Margeta/dctx/blob/main/RELEASING.md --- Document: `RELEASING.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/releasing/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt Releasing dctx View source · Edit on GitHub · Markdown · RELEASING.md · 158 words · updated 7 November 2026 On this page Publication gate and rollback runbook is docs/RELEASING.md . The desktop app retains its separate desktop-v* release workflow. Publication gate # --- url: https://www.dctx.internet.technology/docs/contributing/ title: Contributing source: https://github.com/Eris-Margeta/dctx/blob/main/CONTRIBUTING.md --- Document: `CONTRIBUTING.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/docs/contributing/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt Contributing to dctx View source · Edit on GitHub · Markdown · CONTRIBUTING.md · 546 words · updated 13 November 2026 On this page Bugs, ideas and questions CLI development setup Validation Developer Certificate of Origin Pull requests Read the specification , crate map and Code of Conduct before making changes. Project contributions are licensed under Apache-2.0 , consistent with NOTICE . Bugs, ideas and questions # Search existing issues before opening Report suspected vulnerabilities privately using SECURITY.md , CLI development setup # CI tests use DCTX_CI_RUST from tools/release/toolchain.env ; bump it intentionally each Rust release. Cargo builds dctx-cli , while help text calls the tool dctx . See installation for aliases and install choices. dctx facade serves the CLI and the desktop API; pure engine plugin guide describes effect boundaries and current the website setup , then run tools/website/.venv/bin/python tools/check-markdown-links.py . It checks local Testing documents the full Linux/macOS/Windows matrix and local commands. The current CI workflow runs workspace licence, website and release checks. Run cargo fmt --all -- --check and document public APIs. Follow Rust house style for the plugin boundaries. When editing website source documents, regenerate website/ and check it using the website instructions . Before committing, use check.py --working-tree to compare your regenerated files with an independent the desktop guide . The root just ci recipe also Developer Certificate of Origin # Contributions use the Developer Certificate of Origin The -s flag adds a Signed-off-by: line with your name and email. Pull requests with unsigned commits will be asked to amend them with git commit --amend -s , or to rebase with --signoff . Pull requests # Create a focused branch from main and describe the problem, resulting behavior editing guides. Use clear commit messages, for example fix(cli): reject empty output paths . --- url: https://www.dctx.internet.technology/cli/ title: CLI reference source: https://www.dctx.internet.technology/cli/ --- Reference CLI reference Captured from dctx 1.3.1 when this site was built; a check fails the build when the binary prints anything else. Help text is shown verbatim, so it is the CLI's own wording, including the legacy snapshot options it still lists. What the output looks like # These are real runs on the tiny kiosk sample , captured by capture.py from the release binary. Commands run inside a copy named kiosk . For source builds, the executable is dctx-cli (or define a dctx alias). Pack a project # The header explains the format, the tree assigns IDs, and file blocks carry paths and line counts. The first 40 output lines follow; only the tail is omitted. .env is listed without its contents. $ dctx pack . [DCTX_LLM_CONTEXT_SNAPSHOT_V1] [DIRECTORY:kiosk] <INSTRUCTIONS > 1. Manifest: The <DIRECTORY_TREE > section lists all files. - Each entry: [TYPE] RELATIVE_PATH (ID:UNIQUE_ID) - TYPE is [D] for directory, [F] for file. 2. Content Access: To read a specific file: - Find its UNIQUE_ID from the directory tree. - Search for the marker: <FILE_CONTENT_START ID = "UNIQUE_ID" > - The content is between this marker and </FILE_CONTENT_END ID = "UNIQUE_ID" > </INSTRUCTIONS > <DIRECTORY_TREE > [D] (ID:ROOT) [F] .env (ID:F001) [F] .gitignore (ID:F002) [F] Cargo.toml (ID:F003) [F] README.md (ID:F004) [F] config.toml (ID:F005) [D] src (ID:D006) [F] src/main.rs (ID:F007) [F] src/store.rs (ID:F008) [F] src/util.rs (ID:F009) [D] tools (ID:D010) [F] tools/report.py (ID:F011) [D] web (ID:D012) [F] web/app.ts (ID:F013) [F] web/format.ts (ID:F014) </DIRECTORY_TREE > <FILE_CONTENT_START ID = "F001" PATH = ".env" LINES = "0" > [Content omitted by pattern rules] </FILE_CONTENT_END ID = "F001" > <FILE_CONTENT_START ID = "F002" PATH = ".gitignore" LINES = "2" > target / </FILE_CONTENT_END ID = "F002" > <FILE_CONTENT_START ID = "F003" PATH = "Cargo.toml" LINES = "9" > [package] name = "kiosk" version = "0.1.0" edition = "2021" … (147 more lines) Find a symbol, then read it # Pass the exact ID from find to read to get its metadata and verified source bytes: $ dctx map find greet # kiosk find s:src/util.rs#greet fn L 2 - 4 s:web/app.ts#renderGreeting fn L 10 - 12 $ dctx map read 's:src/util.rs#greet' # kiosk read s:src/util.rs#greet fn src/util.rs pub fn greet(name: &str) -> String { format!("Hello, {}!", title_case(name)) } For structured consumption, --json puts the same source bytes in source_utf8 (one JSON line, shown verbatim): $ dctx map read 's:src/util.rs#greet' --json { "v" : 2 , "place" : "kiosk" , "verb" : "read" , "freshness" :{ "mode" : "strict" , "state" : "verified" }, "precision" :{ "coverage" : "syntax" , "completion" : "complete" , "parser" : "dctx-lex-rust/syn-3.0.9" }, "records" :[{ "id" : "s:src/util.rs#greet" , "kind" : "fn" , "path" : "src/util.rs" , "lines" :[ 2 , 4 ], "summary" : "The greeting shown on the kiosk screen." , "summary_source" : "doc" , "signature" : null , "span" :[ 44 , 126 ], "source_utf8" : "pub fn greet(name: &str) -> String {\n format!(\"Hello, {}!\", title_case(name))\n}" , "edge" : null , "direction" : null , "target" : null , "confidence" : null }], "more" : 0 , "next" : null } Pack for a task # --for uses the task terms to select find results, neighbors and source reads. --budget 800 bounds estimated output tokens, not scan size; the footer reports usage and dropped records. $ dctx pack . --for 'greet store' --budget 800 # dctx pack --for budget = 800 terms = 2 ## find greet s:src/util.rs#greet fn L 2 - 4 s:web/app.ts#renderGreeting fn L 10 - 12 ## find store s:src/store.rs#Order struct L 4 - 8 s:src/store.rs#checksum fn L 22 - 24 s:src/store.rs#encode fn L 17 - 19 ## neighbors s:src/util.rs#greet calls:in:s:src/main.rs#main fn src/main.rs L 7 calls:out:s:src/util.rs#title_case fn src/util.rs contains:in:m:src/util.rs module src/util.rs ## neighbors s:src/store.rs#Order contains:in:m:src/store.rs module src/store.rs ## read s:src/util.rs#greet s:src/util.rs#greet fn src/util.rs pub fn greet(name: &str) -> String { format!("Hello, {}!", title_case(name)) } ## read s:src/store.rs#Order s:src/store.rs#Order struct src/store.rs pub struct Order { pub id: u 32 , pub item: String, pub qty: u 32 , } # end body_tokens = 223 budget = 800 dropped = 0 Usage modes · Rust library and publication status dctx --help General Options Template Commands Examples Feature and precision limits dctx map --help map find neighbors explain read skeleton grep hubs path export languages environment exit codes token estimate dctx --help Usage verbatim Copy Usage: dctx <COMMAND> [ OPTIONS ] dctx pack [ PATH ] [ --output PATH ] [ --clipboard ] [ --json ] dctx pack [ PATH ] --for <TEXT> [ --budget TOKENS ] dctx map <map|find|neighbors|explain|read|skeleton|grep|hubs|path|export> [ --json ] dctx context TARGET [ --place PATH ] [ --budget N] [ --json ] [ --session ID --dedupe ] dctx rpc dctx trace <A> <B> [ --max-depth N] [ --max-paths N] [ --max-bytes N] [ --json ] dctx impact <SYMBOL> [ --max-depth N] [ --max-sites N] [ --max-bytes N] [ --json ] dctx read <TARGET> [ OPTIONS ] dctx languages [ --json | --markdown ] dctx doctor [ --json ] dctx agent-setup [ --format claude|agents|plain] dctx cache status [ --json ] [ --root PATH ] dctx cache gc [ --dry-run ] [ --root PATH ] [ --max-bytes N] dctx cache purge --root PATH [ --dry-run ] [ --yes ] dctx cache purge --all [ --dry-run ] [ --yes ] dctx cache config [auto on|off] [ --max-bytes N] [ --ttl-days N] dctx cache auto [ --json ] dctx template build <PATH> [ --output PATH ] dctx template list [ --dir PATH ] dctx plugin search|install|list|info|enable|disable|remove|update|verify dctx git <status|protect> `dctx languages` lists every supported language with its tier: full (symbols and call edges), outline (symbols only) or docs (sections). `dctx rpc` serves the versioned engine protocol for language packages (send hello first; docs/protocol/ README .md). `dctx read` uses `dctx map read` . Explicit `dctx pack` writes stdout, the clipboard, or `--output` . It does not create a project text file. `dctx pack --for <TEXT>` prints task context for an agent card instead: map find, neighbors and read of the names in TEXT , cut to `--budget` estimated tokens (default 3000 ). `dctx plugin list` and `dctx --help` do not create a project `.dctx/` directory or start a plugin. `dctx git` routes to the bundled dctx /git plugin. It is not a Git passthrough. Cache purge requires `--root PATH` or `--all` , and `--yes` unless `--dry-run` is set. `dctx cache config` shows the persisted policy. `auto on|off` enables auto-clean, `--max-bytes` tightens the system cap, and `--ttl-days` sets idle overlay and preview lifetime. `dctx cache auto` prints the last auto-clean time, the bytes it reclaimed and the next due time. `dctx doctor` lists visible binaries, ownership scopes, SHA -256 checksums and cache sizes without changing the cache or using the network. `dctx agent-setup` prints concise rules to paste into CLAUDE .md or AGENTS .md (default: agents). pack, map, template, plugin and the TUI run one bounded auto-clean when it is due. They print nothing unless bytes were reclaimed. `--no-auto-clean` and `DCTX_AUTO_CLEAN=0` disable that slice. `DCTX_CACHE_DIR` selects the cache parent; indexes live in its engine-major.minor subdirectory. General Options verbatim Copy -h , --help Show help -v , --version Show version --verbose With --version , also show executable path, scope and limits Run `dctx pack --help` for pack options and filters. Template Commands verbatim Copy template build <PATH> Compile a template through the facade template list List explicit compiled plans; no home-directory scan Examples verbatim Copy dctx pack . Pack to stdout and write no project text file dctx pack . --output out.txt dctx languages --json dctx cache status --json dctx cache gc --dry-run dctx cache purge --root /path --dry-run dctx cache config auto off --max-bytes 1000000 --ttl-days 7 dctx cache auto dctx template build policy.dctx_template Feature and precision limits verbatim Copy facade_version: 1 .3.1 profile: enhanced wire_version: 2 segment_version: 1 storage: buffered-segments features: pack,map,templates,fs,segments,cache,syntax-rust parsers: dctx -structural/3,dctx-lex-js:1,dctx-lex-md:1,dctx-lex-rust/syn-3.0.9 languages: rust,javascript,typescript,python,go,java,c,csharp,kotlin,ruby,php,swift,web,scala,dart,zig,solidity,gleam,fortran,perl,groovy,powershell,elixir,lua,ocaml,r,julia,haskell,erlang,verilog,hcl,sql,clojure,lisp,scheme,elisp,config,shell,make,docker,proto,pascal,graphql,nix,markdown,text,rst,asciidoc,org,tex unsafe_boundary: syn-dependency native_code: false git: false subprocess: none precision: the structural extractor reports declarations, imports, headings and conservative calls. It does not promise exact semantic calls, name or type resolution, or macro expansion. A syntax-rust build adds syn for supported Rust syntax only, still without type checking. token estimate: ceil(2 * UTF -8 bytes / 7 ) is an estimate, not a tokenizer guarantee. cache cap: 2 GiB hard, 1 .5 GiB soft watermark, 1 .2 GiB eviction target. cache ttl: idle overlays and previews 7 days, unpinned roots 30 days, staging 1 day. auto-clean interval: 1 day. dctx map --help verbatim Copy Usage: dctx map <map|find|neighbors|explain|read|skeleton|grep> <TARGET> [ OPTIONS ] dctx trace <A> <B> [ --max-depth 1..16 ] [ --max-paths 1..100 ] [ --max-bytes 256..1048576 ] [ --json ] dctx impact <SYMBOL> [ --max-depth 1..16 ] [ --max-sites 1..10000 ] [ --max-bytes 256..1048576 ] [ --json ] dctx map hubs [ --limit N] [ --json ] [ --place PATH ] [ --budget TOKENS ] [ --meta ] Most-called symbols (incoming calls and imports, 1..60 lines, default 20 ) and per-directory file and symbol counts. No TARGET . dctx map path <FROM> <TO> [ --json ] [ --place PATH ] [ --budget TOKENS ] [ --meta ] Shortest edge path (calls, imports, contains; either direction; at most 8 hops), one `edge:out|in<TAB>id<TAB>kind<TAB>path` line per hop, or `no path` . dctx map export [ --format json|mermaid] [ --output PATH ] [ --place PATH ] The whole graph as one deterministic document (default json: nodes and edges; mermaid: a flowchart of calls and imports). No TARGET , no token cap; --output writes a file. TARGET Required. map accepts a stable id or a place-relative file. skeleton takes a file (or m:<path>) and prints its declaration signatures, no bodies, in source order: id, kind, L<start>-<end>, signature. A file path is read as m:<path>. Omitting TARGET does not scan. --json Facade JSON v2, including the precision label --also DIR Add a read-only root (repeatable); paths and ids carry directory labels --place PATH Place or worktree root (default: current directory) --meta Restore the snapshot digest and generation in the text header and the snapshot, generation and age_s JSON fields. Without it the answer bytes do not change across unrelated edits or time. --profile Stderr stage timings and the five slowest files. DCTX_PROFILE = 1 is the same switch. DCTX_MAX_SOURCE_BYTES Env: total source bytes one scan may read, 1..17179869184 (default 1073741824 = 1 GiB). DCTX_MAX_RECORDS Env: files, symbols and edges one index may hold, 1..100000000 (default 1000000 ). A bigger place is refused while it is scanned. DCTX_MAX_ENTRIES Env: files and directories one scan may visit, 1..100000000 (default 100000 ). DCTX_FRESHNESS Env: strict_live hashes every file on a warm start; the default (stamp) trusts a file whose size, mtime and inode are unchanged and older than 2 s. --budget TOKENS Output tokens, 1..2000 (explain max: 1000 ). Read with no --budget uses the 2 ,000-token hard cap. --depth N Map: 1..3 ; neighbors: 1..4 . Explain and read take no depth. --limit N Map, find and neighbors page size. Explain and read accept only 1 . --offset N Refused. Pass the previous page's next value to --cursor . --cursor TOKEN Opaque continuation. A stale token is rejected. --kind fn,type,doc Find kinds --in PATH Find or grep within a relative path grep LITERAL Exhaustive literal search of indexed files, hits grouped by enclosing symbol -i , --ignore-case Grep: ASCII case-insensitive match --edge calls,imports Neighbor edge filter --dir in|out|both Neighbor direction --lines A-B --full Read those absolute source lines inside the node; full permits 400 --rev SHA Refused: this build does not link git Precision: structural declarations, imports, headings and conservative calls. Not exact semantic calls, type resolution or macro expansion. Token estimate ceil(2 * UTF -8 bytes / 7 ) is not a tokenizer guarantee. Example: dctx map find 'ignore rules' --json Example: dctx map map crates/dctx-cli/src/main.rs --depth 2 Example: dctx map map m:crates/dctx-cli/src/main.rs --cursor '<next from the previous page>' Each verb's own page and example: dctx map <verb> --help Exit codes: 0 ok, 1 no result (an id not in the index, a binary file), 2 usage, 3 index error; see docs/ CLI - EXIT - CODES .md. Map verbs dctx map map verbatim Copy Usage: dctx map map <TARGET> [ --depth 1..3 ] [ --limit N] [ --cursor TOKEN ] [ --json ] [ --place PATH ] [ --also DIR ...] [ --meta ] Outline of a file (m:<path> or a place-relative path) or a symbol and what it contains. Example: dctx map map src/lib.rs --depth 2 Every option and its bounds: dctx map --help Examples on the sample dctx map find verbatim Copy Usage: dctx map find <QUERY> [ --kind fn,type,doc] [ --in PATH ] [ --limit 1..40 ] [ --cursor TOKEN ] [ --json ] [ --place PATH ] [ --also DIR ...] [ --meta ] Ranked symbols, modules, headings and config keys whose name or summary matches QUERY . Example: dctx map find 'ignore rules' --json Every option and its bounds: dctx map --help Examples on the sample dctx map neighbors verbatim Copy Usage: dctx map neighbors <TARGET> [ --dir in|out|both] [ --edge calls,imports] [ --depth 1..4 ] [ --limit N] [ --json ] [ --place PATH ] [ --also DIR ...] [ --meta ] Edges of one node: callers with --dir in --edge calls, callees with --dir out. Example: dctx map neighbors 's:src/lib.rs#run' --dir in --edge calls Every option and its bounds: dctx map --help Examples on the sample dctx map explain verbatim Copy Usage: dctx map explain <TARGET> [ --budget 1..1000 ] [ --json ] [ --place PATH ] [ --also DIR ...] [ --meta ] One node with its signature and summary, no body. Example: dctx map explain 's:src/lib.rs#run' Every option and its bounds: dctx map --help Examples on the sample dctx map read verbatim Copy Usage: dctx map read <TARGET> [ --lines A-B] [ --full ] [ --budget TOKENS ] [ --cursor TOKEN ] [ --json ] [ --place PATH ] [ --also DIR ...] [ --meta ] The verified source text of one node; a long node pages with --cursor . Example: dctx map read 's:src/lib.rs#run' --lines 10 -40 Every option and its bounds: dctx map --help Examples on the sample dctx map skeleton verbatim Copy Usage: dctx map skeleton <FILE> [ --budget TOKENS ] [ --json ] [ --place PATH ] [ --also DIR ...] [ --meta ] Declaration signatures of one file in source order, no bodies. Example: dctx map skeleton src/lib.rs Every option and its bounds: dctx map --help Examples on the sample dctx map grep verbatim Copy Usage: dctx map grep <LITERAL> [ -i ] [ --in PATH ] [ --limit N] [ --json ] [ --place PATH ] [ --also DIR ...] [ --meta ] Exhaustive literal search of indexed files, hits grouped by enclosing symbol. Example: dctx map grep TODO --in src Every option and its bounds: dctx map --help Examples on the sample dctx map hubs verbatim Copy Usage: dctx map hubs [ --limit 1..60 ] [ --budget TOKENS ] [ --json ] [ --place PATH ] [ --also DIR ...] [ --meta ] Most-called symbols and per-directory file and symbol counts. No TARGET . Example: dctx map hubs --limit 10 Every option and its bounds: dctx map --help Examples on the sample dctx map path verbatim Copy Usage: dctx map path <FROM> <TO> [ --budget TOKENS ] [ --json ] [ --place PATH ] [ --also DIR ...] [ --meta ] Shortest edge path (calls, imports, contains; at most 8 hops) between two nodes, or `no path` . Example: dctx map path 's:src/main.rs#main' 's:src/lib.rs#run' Every option and its bounds: dctx map --help Examples on the sample dctx map export verbatim Copy Usage: dctx map export [ --format json|mermaid] [ --output PATH ] [ --place PATH ] [ --also DIR ...] The whole graph as one deterministic document. No TARGET , no token cap. Example: dctx map export --format mermaid --output graph.mmd Every option and its bounds: dctx map --help Examples on the sample dctx languages verbatim Copy Usage: dctx languages [ --json | --markdown ] Lists every language the map index recognises: name, tag, file names, tier and symbol confidence. Tiers: full = symbols and call edges (lexical, not type-resolved); outline = symbols only, no call edges promised; docs = headed sections. Confidence `guess` marks heuristic outlines, whose records carry confidence `guess` . Options: --json One JSON document with the tiers and the languages --markdown The README language table -h , --help Show this help Example: dctx languages --json 50 languages: 36 full, 8 outline, 6 docs. The table with every tag and file name is on /languages/ . Environment variables Variable Help text Printed by DCTX_MAX_SOURCE_BYTES DCTX_MAX_SOURCE_BYTES Env: total source bytes one scan may read, 1..17179869184 (default 1073741824 = 1 GiB). dctx map --help DCTX_MAX_RECORDS DCTX_MAX_RECORDS Env: files, symbols and edges one index may hold, 1..100000000 (default 1000000). A bigger place is refused while it is scanned. dctx map --help DCTX_MAX_ENTRIES DCTX_MAX_ENTRIES Env: files and directories one scan may visit, 1..100000000 (default 100000). dctx map --help DCTX_FRESHNESS DCTX_FRESHNESS Env: strict_live hashes every file on a warm start; the default (stamp) trusts a file whose size, mtime and inode are unchanged and older than 2 s. dctx map --help DCTX_CACHE_DIR --no-auto-clean and DCTX_AUTO_CLEAN=0 disable that slice. DCTX_CACHE_DIR selects the cache parent; indexes live in its engine-major.minor subdirectory. dctx --help DCTX_AUTO_CLEAN --no-auto-clean and DCTX_AUTO_CLEAN=0 disable that slice. DCTX_CACHE_DIR selects the cache parent; indexes live in its engine-major.minor subdirectory. dctx --help DCTX_PROFILE --profile Stderr stage timings and the five slowest files. DCTX_PROFILE=1 is the same switch. dctx map --help Exit codes CLI-EXIT-CODES.md · full contract Code Meaning Examples 0 ok: the command answered a find page, including one with no hits; --help 1 no result: the command ran, but the named target or input has no answer map read m:nope.py (an id not in the index); map read logo.png (a binary file); pack of a directory with no packable file 2 usage: the arguments are wrong an unknown command or flag; a missing target ( dctx context with no TARGET); --depth 9 ; an empty find query; a stale --cursor ; m:../outside ; a non-UTF-8 argument; cache purge without --root / --all or --yes ; a template that does not compile; a bare dctx whose stdin or stdout is not a terminal 3 index error: the place, source, cache or index could not be opened, read, built or written --place /no/such/dir ; a corrupt or busy cache; a source over DCTX_MAX_SOURCE_BYTES ; an --output file that cannot be written; template build /no/such/file (the message names the path) Token estimate Every byte and token count on this site uses the estimate dctx itself prints: verbatim Copy token estimate: ceil(2 * UTF -8 bytes / 7 ) is an estimate, not a tokenizer guarantee. --- url: https://www.dctx.internet.technology/languages/ title: Languages source: https://www.dctx.internet.technology/languages/ --- Reference Languages 50 language families in three tiers: 36 full, 8 outline and 6 documentation formats. The table is the output of dctx languages --markdown , captured from dctx 1.3.1. dctx languages prints this table ( --json for tools, --markdown for this block) from the one registry that also drives dctx --version --verbose ; a test fails when the block below differs from it. full : symbols and call edges. Call edges are lexical, not type-resolved: they come from names, scopes and imports, never from a type checker, and ambiguous references are dropped. outline : symbols only; no call edges are promised. Shell function bodies can yield same-file call guesses, but v1 does not promise shell call edges. docs : headed sections. Confidence : guess marks the heuristic outline families, and every record from those files carries confidence guess ; structural means a dedicated lexer or deterministic document rules. Full language table README: Language tiers Click a column heading to sort. Language Tag Files Tier Confidence Rust rust .rs full structural JavaScript javascript .js, .mjs, .cjs, .jsx full structural TypeScript/TSX typescript .ts, .mts, .cts, .tsx full structural Python python .py, .pyi full structural Go go .go full structural Java java .java full structural C/C++ c .c, .h, .cc, .cpp, .cxx, .hpp, .hh full structural C# csharp .cs full structural Kotlin kotlin .kt, .kts full structural Ruby ruby .rb, .rake, .gemspec, Rakefile, Gemfile full structural PHP php .php, .phtml, .inc full structural Swift swift .swift full structural Vue/Svelte/Astro/HTML script blocks web .vue, .svelte, .astro, .html, .htm full structural Scala scala .scala, .sc full guess Dart dart .dart full guess Zig zig .zig full guess Solidity solidity .sol full guess Gleam gleam .gleam full guess Fortran fortran .f90, .f95, .f03, .f08, .f, .for full guess Perl perl .pl, .pm, .t, .psgi full guess Groovy groovy .groovy, .gradle full guess PowerShell powershell .ps1, .psm1, .psd1 full guess Elixir elixir .ex, .exs full guess Lua lua .lua full guess OCaml ocaml .ml, .mli full guess R r .r full guess Julia julia .jl full guess Haskell haskell .hs full guess Erlang erlang .erl, .hrl full guess Verilog/SystemVerilog verilog .v, .vh, .sv, .svh full guess Terraform/HCL hcl .tf, .tfvars, .hcl full guess SQL sql .sql, *.sql.in full guess Clojure clojure .clj, .cljs, .cljc, .edn full guess Common Lisp lisp .lisp, .lsp, .cl full guess Scheme scheme .scm, .ss full guess Emacs Lisp elisp .el full guess JSON/JSONC/TOML/YAML config .json, .jsonc, .toml, .yaml, .yml outline structural Shell shell .sh, .bash, .zsh, .bats outline guess Makefile make .mk, Makefile, GNUmakefile outline guess Dockerfile docker Dockerfile, Containerfile outline guess Protobuf proto .proto outline guess Pascal pascal .pas, .pp, .dpr outline guess GraphQL graphql .graphql, .gql outline guess Nix nix .nix outline guess Markdown markdown .md, .markdown docs structural Plain text text .txt docs structural reStructuredText rst .rst docs structural AsciiDoc asciidoc .adoc, .asciidoc docs structural Org org .org docs structural LaTeX tex .tex docs structural --- url: https://www.dctx.internet.technology/examples/ title: Examples source: https://www.dctx.internet.technology/examples/ --- Examples Examples 40 runs of dctx 1.3.1 on one small project, recorded when this site was built: the exact stdout and stderr, the exit code, the bytes and the estimated tokens ( ceil(2 × bytes / 7) ). Each run starts from an empty home, config and cache (DCTX_AUTO_CLEAN=0, LC_ALL=C.UTF-8, COLUMNS=100), in a copy of the sample named kiosk . Wall time is not recorded. The 13 files of the sample, and what dctx pack . did with each (derived from the captured runs). tools/website/sample File Bytes In pack .env 29 listed-not-read .gitignore 8 packed Cargo.toml 185 packed README.md 473 packed assets/logo.png 69 binary config.toml 78 packed src/main.rs 331 packed src/store.rs 698 packed src/util.rs 404 packed target/debug/kiosk.d 42 ignored tools/report.py 484 packed web/app.ts 596 packed web/format.ts 350 packed Only three values are not stable between runs and are replaced with … , each where it occurs: the commit hash in --version , the MOD: times of --tree-stamps=on and age_s of --meta . The help pages are on /cli/ , the template builds on /templates/ . The same commands run live in the playground . Pack (6) Map, text (9) Map, JSON (4) Graph export (2) Errors and exit codes (3) Pack dctx --version exit 0 23 bytes ~7 est. tokens kiosk $ dctx --version dctx 1.3.1 (<git sha>) # exit 0 · 23 bytes · ~7 est. tokens dctx pack . exit 0 5,545 bytes ~1,585 est. tokens The whole project as one block. .env is listed by name and never read; target/ (ignored by .gitignore) and the binary assets/logo.png are left out. kiosk $ dctx pack . [DCTX_LLM_CONTEXT_SNAPSHOT_V1] [DIRECTORY:kiosk] <INSTRUCTIONS > 1. Manifest: The <DIRECTORY_TREE > section lists all files. - Each entry: [TYPE] RELATIVE_PATH (ID:UNIQUE_ID) - TYPE is [D] for directory, [F] for file. 2. Content Access: To read a specific file: - Find its UNIQUE_ID from the directory tree. - Search for the marker: <FILE_CONTENT_START ID = "UNIQUE_ID" > - The content is between this marker and </FILE_CONTENT_END ID = "UNIQUE_ID" > </INSTRUCTIONS > <DIRECTORY_TREE > [D] (ID:ROOT) [F] .env (ID:F001) [F] .gitignore (ID:F002) [F] Cargo.toml (ID:F003) [F] README.md (ID:F004) [F] config.toml (ID:F005) [D] src (ID:D006) [F] src/main.rs (ID:F007) [F] src/store.rs (ID:F008) [F] src/util.rs (ID:F009) [D] tools (ID:D010) [F] tools/report.py (ID:F011) [D] web (ID:D012) [F] web/app.ts (ID:F013) [F] web/format.ts (ID:F014) </DIRECTORY_TREE > <FILE_CONTENT_START ID = "F001" PATH = ".env" LINES = "0" > [Content omitted by pattern rules] </FILE_CONTENT_END ID = "F001" > <FILE_CONTENT_START ID = "F002" PATH = ".gitignore" LINES = "2" > target / </FILE_CONTENT_END ID = "F002" > <FILE_CONTENT_START ID = "F003" PATH = "Cargo.toml" LINES = "9" > [package] name = "kiosk" version = "0.1.0" edition = "2021" description = "A tiny order kiosk: the sample project for the dctx website examples." license = "Apache-2.0" [dependencies] </FILE_CONTENT_END ID = "F003" > <FILE_CONTENT_START ID = "F004" PATH = "README.md" LINES = "19" > # kiosk A tiny order kiosk. It is the example project that every command on the dctx website runs on. ## Run cargo run -- ada prints `Hello, Ada!` and saves order 1 to `orders/1.tsv` . ## Orders Each order is one tab-separated line: id, item, quantity and a checksum of the item name. `python3 tools/report.py orders/` sums the quantities. ## Configuration `config.toml` holds the currency and the screen title. Secrets live in `.env` , which is never committed. </FILE_CONTENT_END ID = "F004" > <FILE_CONTENT_START ID = "F005" PATH = "config.toml" LINES = "7" > [screen] title = "kiosk example" currency = "EUR" [orders] folder = "orders" </FILE_CONTENT_END ID = "F005" > <FILE_CONTENT_START ID = "F007" PATH = "src/main.rs" LINES = "11" > //! kiosk: greet a customer, take one order, save it. mod store ; mod util ; fn main () { let name = std::env:: args (). nth ( 1 ). unwrap_or_else (|| "guest" . to_string ()); println! ( "{}" , util:: greet (&name)); let order = store:: Order { id: 1 , item: "coffee" . to_string (), qty: 2 }; store:: save (&order). expect ( "save order" ); } </FILE_CONTENT_END ID = "F007" > <FILE_CONTENT_START ID = "F008" PATH = "src/store.rs" LINES = "25" > use std::io; /// One order as the kiosk records it. pub struct Order { pub id: u32 , pub item: String , pub qty: u32 , } /// Write the order to orders/<id>.tsv. pub fn save (order: & Order ) -> io:: Result <()> { std::fs:: create_dir_all ( "orders" )?; std::fs:: write ( format! ( "orders/{}.tsv" , order.id), encode (order)) } /// One tab-separated line with a checksum of the item name. fn encode (order: & Order ) -> String { format! ( "{}\t{}\t{}\t{:08x}\n" , order.id, order.item, order.qty, checksum (&order.item)) } /// FNV-1a over the bytes of the text. fn checksum (text: & str ) -> u32 { text. bytes (). fold ( 0x811c9dc5 , |hash, byte| (hash ^ u32 :: from (byte)). wrapping_mul ( 0x0100_0193 )) } </FILE_CONTENT_END ID = "F008" > <FILE_CONTENT_START ID = "F009" PATH = "src/util.rs" LINES = "14" > /// The greeting shown on the kiosk screen. pub fn greet (name: & str ) -> String { format! ( "Hello, {}!" , title_case (name)) } /// Upper-case the first letter of a name, leave the rest as typed. pub fn title_case (name: & str ) -> String { let mut chars = name. chars (); match chars. next () { Some (first) => first. to_uppercase (). chain (chars). collect (), None => String :: new (), } } </FILE_CONTENT_END ID = "F009" > <FILE_CONTENT_START ID = "F011" PATH = "tools/report.py" LINES = "19" > """Sum the quantities of every saved order: python3 tools/report.py orders/""" import sys from pathlib import Path def read_orders (folder): for path in sorted ( Path (folder). glob ( "*.tsv" )): order_id, item, qty, _checksum = path. read_text (). rstrip ( "\n" ). split ( "\t" ) yield order_id, item, int (qty) def main (folder= "orders" ): total = sum (qty for _, _, qty in read_orders (folder)) print ( f"{total} items" ) if __name__ == "__main__" : main (*sys.argv[ 1 :]) </FILE_CONTENT_END ID = "F011" > <FILE_CONTENT_START ID = "F013" PATH = "web/app.ts" LINES = "20" > import { formatName, formatPrice } from "./format" ; interface Line { item: string ; cents: number ; qty: number ; } /** The greeting banner of the kiosk web screen. */ export function renderGreeting (name: string ): string { return `Hello, ${formatName(name)}!` ; } /** One receipt line per order line, then the total. */ export function renderReceipt (lines: Line []): string [] { const rows = lines. map ((l) => `${l.qty} x ${l.item} ${formatPrice(l.cents * l.qty)}` ); const total = lines. reduce ((sum, l) => sum + l.cents * l.qty, 0 ); return [...rows, `total ${formatPrice(total)}` ]; } </FILE_CONTENT_END ID = "F013" > <FILE_CONTENT_START ID = "F014" PATH = "web/format.ts" LINES = "10" > /** Price in cents to a display string, e.g. 250 -> "2.50 EUR". */ export function formatPrice (cents: number , currency = "EUR" ): string { return `${(cents / 100).toFixed(2)} ${currency}` ; } /** The customer's name as the screen shows it. */ export function formatName (name: string ): string { return name. trim () === "" ? "guest" : name. trim (); } </FILE_CONTENT_END ID = "F014" > pack bytes=5545 files=11 retention=stdout version=V1 # exit 0 · 5,545 bytes · ~1,585 est. tokens dctx pack . --tree-stamps=on exit 0 5,801 bytes ~1,658 est. tokens The 1.0.0 tree lines with MOD and SIZE. MOD is a modification time in milliseconds and differs on every checkout, so its digits are replaced with … here. kiosk $ dctx pack . --tree-stamps= on [DCTX_LLM_CONTEXT_SNAPSHOT_V1] [DIRECTORY:kiosk] <INSTRUCTIONS > 1. Manifest: The <DIRECTORY_TREE > section lists all files. - Each entry: [TYPE] RELATIVE_PATH (ID:UNIQUE_ID, MOD:TIMESTAMP) - TYPE is [D] for directory, [F] for file. 2. Content Access: To read a specific file: - Find its UNIQUE_ID from the directory tree. - Search for the marker: <FILE_CONTENT_START ID = "UNIQUE_ID" > - The content is between this marker and </FILE_CONTENT_END ID = "UNIQUE_ID" > </INSTRUCTIONS > <DIRECTORY_TREE > [D] (ID:ROOT, MOD:…) [F] .env (ID:F001, MOD:…, SIZE:29) [F] .gitignore (ID:F002, MOD:…, SIZE:8) [F] Cargo.toml (ID:F003, MOD:…, SIZE:185) [F] README.md (ID:F004, MOD:…, SIZE:473) [F] config.toml (ID:F005, MOD:…, SIZE:78) [D] src (ID:D006, MOD:…) [F] src/main.rs (ID:F007, MOD:…, SIZE:331) [F] src/store.rs (ID:F008, MOD:…, SIZE:698) [F] src/util.rs (ID:F009, MOD:…, SIZE:404) [D] tools (ID:D010, MOD:…) [F] tools/report.py (ID:F011, MOD:…, SIZE:484) [D] web (ID:D012, MOD:…) [F] web/app.ts (ID:F013, MOD:…, SIZE:596) [F] web/format.ts (ID:F014, MOD:…, SIZE:350) </DIRECTORY_TREE > <FILE_CONTENT_START ID = "F001" PATH = ".env" LINES = "0" > [Content omitted by pattern rules] </FILE_CONTENT_END ID = "F001" > <FILE_CONTENT_START ID = "F002" PATH = ".gitignore" LINES = "2" > target / </FILE_CONTENT_END ID = "F002" > <FILE_CONTENT_START ID = "F003" PATH = "Cargo.toml" LINES = "9" > [package] name = "kiosk" version = "0.1.0" edition = "2021" description = "A tiny order kiosk: the sample project for the dctx website examples." license = "Apache-2.0" [dependencies] </FILE_CONTENT_END ID = "F003" > <FILE_CONTENT_START ID = "F004" PATH = "README.md" LINES = "19" > # kiosk A tiny order kiosk. It is the example project that every command on the dctx website runs on. ## Run cargo run -- ada prints `Hello, Ada!` and saves order 1 to `orders/1.tsv` . ## Orders Each order is one tab-separated line: id, item, quantity and a checksum of the item name. `python3 tools/report.py orders/` sums the quantities. ## Configuration `config.toml` holds the currency and the screen title. Secrets live in `.env` , which is never committed. </FILE_CONTENT_END ID = "F004" > <FILE_CONTENT_START ID = "F005" PATH = "config.toml" LINES = "7" > [screen] title = "kiosk example" currency = "EUR" [orders] folder = "orders" </FILE_CONTENT_END ID = "F005" > <FILE_CONTENT_START ID = "F007" PATH = "src/main.rs" LINES = "11" > //! kiosk: greet a customer, take one order, save it. mod store ; mod util ; fn main () { let name = std::env:: args (). nth ( 1 ). unwrap_or_else (|| "guest" . to_string ()); println! ( "{}" , util:: greet (&name)); let order = store:: Order { id: 1 , item: "coffee" . to_string (), qty: 2 }; store:: save (&order). expect ( "save order" ); } </FILE_CONTENT_END ID = "F007" > <FILE_CONTENT_START ID = "F008" PATH = "src/store.rs" LINES = "25" > use std::io; /// One order as the kiosk records it. pub struct Order { pub id: u32 , pub item: String , pub qty: u32 , } /// Write the order to orders/<id>.tsv. pub fn save (order: & Order ) -> io:: Result <()> { std::fs:: create_dir_all ( "orders" )?; std::fs:: write ( format! ( "orders/{}.tsv" , order.id), encode (order)) } /// One tab-separated line with a checksum of the item name. fn encode (order: & Order ) -> String { format! ( "{}\t{}\t{}\t{:08x}\n" , order.id, order.item, order.qty, checksum (&order.item)) } /// FNV-1a over the bytes of the text. fn checksum (text: & str ) -> u32 { text. bytes (). fold ( 0x811c9dc5 , |hash, byte| (hash ^ u32 :: from (byte)). wrapping_mul ( 0x0100_0193 )) } </FILE_CONTENT_END ID = "F008" > <FILE_CONTENT_START ID = "F009" PATH = "src/util.rs" LINES = "14" > /// The greeting shown on the kiosk screen. pub fn greet (name: & str ) -> String { format! ( "Hello, {}!" , title_case (name)) } /// Upper-case the first letter of a name, leave the rest as typed. pub fn title_case (name: & str ) -> String { let mut chars = name. chars (); match chars. next () { Some (first) => first. to_uppercase (). chain (chars). collect (), None => String :: new (), } } </FILE_CONTENT_END ID = "F009" > <FILE_CONTENT_START ID = "F011" PATH = "tools/report.py" LINES = "19" > """Sum the quantities of every saved order: python3 tools/report.py orders/""" import sys from pathlib import Path def read_orders (folder): for path in sorted ( Path (folder). glob ( "*.tsv" )): order_id, item, qty, _checksum = path. read_text (). rstrip ( "\n" ). split ( "\t" ) yield order_id, item, int (qty) def main (folder= "orders" ): total = sum (qty for _, _, qty in read_orders (folder)) print ( f"{total} items" ) if __name__ == "__main__" : main (*sys.argv[ 1 :]) </FILE_CONTENT_END ID = "F011" > <FILE_CONTENT_START ID = "F013" PATH = "web/app.ts" LINES = "20" > import { formatName, formatPrice } from "./format" ; interface Line { item: string ; cents: number ; qty: number ; } /** The greeting banner of the kiosk web screen. */ export function renderGreeting (name: string ): string { return `Hello, ${formatName(name)}!` ; } /** One receipt line per order line, then the total. */ export function renderReceipt (lines: Line []): string [] { const rows = lines. map ((l) => `${l.qty} x ${l.item} ${formatPrice(l.cents * l.qty)}` ); const total = lines. reduce ((sum, l) => sum + l.cents * l.qty, 0 ); return [...rows, `total ${formatPrice(total)}` ]; } </FILE_CONTENT_END ID = "F013" > <FILE_CONTENT_START ID = "F014" PATH = "web/format.ts" LINES = "10" > /** Price in cents to a display string, e.g. 250 -> "2.50 EUR". */ export function formatPrice (cents: number , currency = "EUR" ): string { return `${(cents / 100).toFixed(2)} ${currency}` ; } /** The customer's name as the screen shows it. */ export function formatName (name: string ): string { return name. trim () === "" ? "guest" : name. trim (); } </FILE_CONTENT_END ID = "F014" > pack bytes=5951 files=11 retention=stdout version=V1 # exit 0 · 5,801 bytes · ~1,658 est. tokens dctx pack . --ext rs exit 0 2,345 bytes ~670 est. tokens Only the Rust files. kiosk $ dctx pack . --ext rs [DCTX_LLM_CONTEXT_SNAPSHOT_V1] [DIRECTORY:kiosk] <INSTRUCTIONS > 1. Manifest: The <DIRECTORY_TREE > section lists all files. - Each entry: [TYPE] RELATIVE_PATH (ID:UNIQUE_ID) - TYPE is [D] for directory, [F] for file. 2. Content Access: To read a specific file: - Find its UNIQUE_ID from the directory tree. - Search for the marker: <FILE_CONTENT_START ID = "UNIQUE_ID" > - The content is between this marker and </FILE_CONTENT_END ID = "UNIQUE_ID" > </INSTRUCTIONS > <DIRECTORY_TREE > [D] (ID:ROOT) [D] src (ID:D001) [F] src/main.rs (ID:F002) [F] src/store.rs (ID:F003) [F] src/util.rs (ID:F004) </DIRECTORY_TREE > <FILE_CONTENT_START ID = "F002" PATH = "src/main.rs" LINES = "11" > //! kiosk: greet a customer, take one order, save it. mod store ; mod util ; fn main () { let name = std::env:: args (). nth ( 1 ). unwrap_or_else (|| "guest" . to_string ()); println! ( "{}" , util:: greet (&name)); let order = store:: Order { id: 1 , item: "coffee" . to_string (), qty: 2 }; store:: save (&order). expect ( "save order" ); } </FILE_CONTENT_END ID = "F002" > <FILE_CONTENT_START ID = "F003" PATH = "src/store.rs" LINES = "25" > use std::io; /// One order as the kiosk records it. pub struct Order { pub id: u32 , pub item: String , pub qty: u32 , } /// Write the order to orders/<id>.tsv. pub fn save (order: & Order ) -> io:: Result <()> { std::fs:: create_dir_all ( "orders" )?; std::fs:: write ( format! ( "orders/{}.tsv" , order.id), encode (order)) } /// One tab-separated line with a checksum of the item name. fn encode (order: & Order ) -> String { format! ( "{}\t{}\t{}\t{:08x}\n" , order.id, order.item, order.qty, checksum (&order.item)) } /// FNV-1a over the bytes of the text. fn checksum (text: & str ) -> u32 { text. bytes (). fold ( 0x811c9dc5 , |hash, byte| (hash ^ u32 :: from (byte)). wrapping_mul ( 0x0100_0193 )) } </FILE_CONTENT_END ID = "F003" > <FILE_CONTENT_START ID = "F004" PATH = "src/util.rs" LINES = "14" > /// The greeting shown on the kiosk screen. pub fn greet (name: & str ) -> String { format! ( "Hello, {}!" , title_case (name)) } /// Upper-case the first letter of a name, leave the rest as typed. pub fn title_case (name: & str ) -> String { let mut chars = name. chars (); match chars. next () { Some (first) => first. to_uppercase (). chain (chars). collect (), None => String :: new (), } } </FILE_CONTENT_END ID = "F004" > pack bytes=2345 files=3 retention=stdout version=V1 # exit 0 · 2,345 bytes · ~670 est. tokens dctx pack . --debug-ignored exit 0 5,670 bytes ~1,620 est. tokens Ignored paths are listed with [IGNORED] and never read: the content of target/ does not appear. kiosk $ dctx pack . --debug-ignored [DCTX_LLM_CONTEXT_SNAPSHOT_V1] [DIRECTORY:kiosk] <INSTRUCTIONS > 1. Manifest: The <DIRECTORY_TREE > section lists all files. - Each entry: [TYPE] RELATIVE_PATH (ID:UNIQUE_ID) - TYPE is [D] for directory, [F] for file. 2. Content Access: To read a specific file: - Find its UNIQUE_ID from the directory tree. - Search for the marker: <FILE_CONTENT_START ID = "UNIQUE_ID" > - The content is between this marker and </FILE_CONTENT_END ID = "UNIQUE_ID" > </INSTRUCTIONS > <DIRECTORY_TREE > [D] (ID:ROOT) [F] .env (ID:F001) [F] .gitignore (ID:F002) [F] Cargo.toml (ID:F003) [F] README.md (ID:F004) [F] config.toml (ID:F005) [D] src (ID:D006) [F] src/main.rs (ID:F007) [F] src/store.rs (ID:F008) [F] src/util.rs (ID:F009) [D] target [IGNORED] (ID:D010) [D] target/debug [IGNORED] (ID:D011) [F] target/debug/kiosk.d [IGNORED] (ID:F012) [D] tools (ID:D013) [F] tools/report.py (ID:F014) [D] web (ID:D015) [F] web/app.ts (ID:F016) [F] web/format.ts (ID:F017) </DIRECTORY_TREE > <FILE_CONTENT_START ID = "F001" PATH = ".env" LINES = "0" > [Content omitted by pattern rules] </FILE_CONTENT_END ID = "F001" > <FILE_CONTENT_START ID = "F002" PATH = ".gitignore" LINES = "2" > target / </FILE_CONTENT_END ID = "F002" > <FILE_CONTENT_START ID = "F003" PATH = "Cargo.toml" LINES = "9" > [package] name = "kiosk" version = "0.1.0" edition = "2021" description = "A tiny order kiosk: the sample project for the dctx website examples." license = "Apache-2.0" [dependencies] </FILE_CONTENT_END ID = "F003" > <FILE_CONTENT_START ID = "F004" PATH = "README.md" LINES = "19" > # kiosk A tiny order kiosk. It is the example project that every command on the dctx website runs on. ## Run cargo run -- ada prints `Hello, Ada!` and saves order 1 to `orders/1.tsv` . ## Orders Each order is one tab-separated line: id, item, quantity and a checksum of the item name. `python3 tools/report.py orders/` sums the quantities. ## Configuration `config.toml` holds the currency and the screen title. Secrets live in `.env` , which is never committed. </FILE_CONTENT_END ID = "F004" > <FILE_CONTENT_START ID = "F005" PATH = "config.toml" LINES = "7" > [screen] title = "kiosk example" currency = "EUR" [orders] folder = "orders" </FILE_CONTENT_END ID = "F005" > <FILE_CONTENT_START ID = "F007" PATH = "src/main.rs" LINES = "11" > //! kiosk: greet a customer, take one order, save it. mod store ; mod util ; fn main () { let name = std::env:: args (). nth ( 1 ). unwrap_or_else (|| "guest" . to_string ()); println! ( "{}" , util:: greet (&name)); let order = store:: Order { id: 1 , item: "coffee" . to_string (), qty: 2 }; store:: save (&order). expect ( "save order" ); } </FILE_CONTENT_END ID = "F007" > <FILE_CONTENT_START ID = "F008" PATH = "src/store.rs" LINES = "25" > use std::io; /// One order as the kiosk records it. pub struct Order { pub id: u32 , pub item: String , pub qty: u32 , } /// Write the order to orders/<id>.tsv. pub fn save (order: & Order ) -> io:: Result <()> { std::fs:: create_dir_all ( "orders" )?; std::fs:: write ( format! ( "orders/{}.tsv" , order.id), encode (order)) } /// One tab-separated line with a checksum of the item name. fn encode (order: & Order ) -> String { format! ( "{}\t{}\t{}\t{:08x}\n" , order.id, order.item, order.qty, checksum (&order.item)) } /// FNV-1a over the bytes of the text. fn checksum (text: & str ) -> u32 { text. bytes (). fold ( 0x811c9dc5 , |hash, byte| (hash ^ u32 :: from (byte)). wrapping_mul ( 0x0100_0193 )) } </FILE_CONTENT_END ID = "F008" > <FILE_CONTENT_START ID = "F009" PATH = "src/util.rs" LINES = "14" > /// The greeting shown on the kiosk screen. pub fn greet (name: & str ) -> String { format! ( "Hello, {}!" , title_case (name)) } /// Upper-case the first letter of a name, leave the rest as typed. pub fn title_case (name: & str ) -> String { let mut chars = name. chars (); match chars. next () { Some (first) => first. to_uppercase (). chain (chars). collect (), None => String :: new (), } } </FILE_CONTENT_END ID = "F009" > <FILE_CONTENT_START ID = "F014" PATH = "tools/report.py" LINES = "19" > """Sum the quantities of every saved order: python3 tools/report.py orders/""" import sys from pathlib import Path def read_orders (folder): for path in sorted ( Path (folder). glob ( "*.tsv" )): order_id, item, qty, _checksum = path. read_text (). rstrip ( "\n" ). split ( "\t" ) yield order_id, item, int (qty) def main (folder= "orders" ): total = sum (qty for _, _, qty in read_orders (folder)) print ( f"{total} items" ) if __name__ == "__main__" : main (*sys.argv[ 1 :]) </FILE_CONTENT_END ID = "F014" > <FILE_CONTENT_START ID = "F016" PATH = "web/app.ts" LINES = "20" > import { formatName, formatPrice } from "./format" ; interface Line { item: string ; cents: number ; qty: number ; } /** The greeting banner of the kiosk web screen. */ export function renderGreeting (name: string ): string { return `Hello, ${formatName(name)}!` ; } /** One receipt line per order line, then the total. */ export function renderReceipt (lines: Line []): string [] { const rows = lines. map ((l) => `${l.qty} x ${l.item} ${formatPrice(l.cents * l.qty)}` ); const total = lines. reduce ((sum, l) => sum + l.cents * l.qty, 0 ); return [...rows, `total ${formatPrice(total)}` ]; } </FILE_CONTENT_END ID = "F016" > <FILE_CONTENT_START ID = "F017" PATH = "web/format.ts" LINES = "10" > /** Price in cents to a display string, e.g. 250 -> "2.50 EUR". */ export function formatPrice (cents: number , currency = "EUR" ): string { return `${(cents / 100).toFixed(2)} ${currency}` ; } /** The customer's name as the screen shows it. */ export function formatName (name: string ): string { return name. trim () === "" ? "guest" : name. trim (); } </FILE_CONTENT_END ID = "F017" > pack bytes=5670 files=12 retention=stdout version=V1 # exit 0 · 5,670 bytes · ~1,620 est. tokens dctx pack . --for 'greet store' --budget 800 exit 0 822 bytes ~235 est. tokens Task context for an agent: find, neighbors and read of the names in the text, cut to the estimated output-token budget. kiosk $ dctx pack . --for 'greet store' --budget 800 # dctx pack --for budget = 800 terms = 2 ## find greet s:src/util.rs#greet fn L2-4 s:web/app.ts#renderGreeting fn L10-12 ## find store s:src/store.rs#Order struct L4-8 s:src/store.rs#checksum fn L22-24 s:src/store.rs#encode fn L17-19 ## neighbors s:src/util.rs#greet calls:in: s:src/main.rs#main fn src/main.rs L7 calls:out: s:src/util.rs#title_case fn src/util.rs contains:in: m:src/util.rs module src/util.rs ## neighbors s:src/store.rs#Order contains:in: m:src/store.rs module src/store.rs ## read s:src/util.rs#greet s:src/util.rs#greet fn src/util.rs pub fn greet (name: & str ) -> String { format! ( "Hello, {}!" , title_case (name)) } ## read s:src/store.rs#Order s:src/store.rs#Order struct src/store.rs pub struct Order { pub id: u32 , pub item: String , pub qty: u32 , } # end body_tokens = 223 budget = 800 dropped = 0 # exit 0 · 822 bytes · ~235 est. tokens Map, text dctx map map src/util.rs --depth 2 exit 0 74 bytes ~22 est. tokens Outline of one file. kiosk $ dctx map map src/util.rs --depth 2 # kiosk map s:src/util.rs#greet fn L2-4 s:src/util.rs#title_case fn L7-13 # exit 0 · 74 bytes · ~22 est. tokens dctx map find greet exit 0 79 bytes ~23 est. tokens kiosk $ dctx map find greet # kiosk find s:src/util.rs#greet fn L2-4 s:web/app.ts#renderGreeting fn L10-12 # exit 0 · 79 bytes · ~23 est. tokens dctx map read 's:src/util.rs#greet' exit 0 131 bytes ~38 est. tokens Read the symbol metadata and verified source bytes; --json puts the source in source_utf8. kiosk $ dctx map read 's:src/util.rs#greet' # kiosk read s:src/util.rs#greet fn src/util.rs pub fn greet (name: & str ) -> String { format! ( "Hello, {}!" , title_case (name)) } # exit 0 · 131 bytes · ~38 est. tokens dctx map neighbors 's:src/util.rs#greet' --edge calls --dir in exit 0 64 bytes ~19 est. tokens Callers, with the call-site line. kiosk $ dctx map neighbors 's:src/util.rs#greet' --edge calls --dir in # kiosk neighbors calls:in: s:src/main.rs#main fn src/main.rs L7 # exit 0 · 64 bytes · ~19 est. tokens dctx map explain 's:src/util.rs#greet' exit 0 51 bytes ~15 est. tokens kiosk $ dctx map explain 's:src/util.rs#greet' # kiosk explain s:src/util.rs#greet fn src/util.rs # exit 0 · 51 bytes · ~15 est. tokens dctx map skeleton src/store.rs exit 0 280 bytes ~80 est. tokens Declaration signatures, no bodies, in source order. kiosk $ dctx map skeleton src/store.rs # kiosk skeleton m:src/store.rs module L1-24 src/store.rs s:src/store.rs#Order struct L4-8 pub struct Order s:src/store.rs#save fn L11-14 pub fn save (order: & Order ) s:src/store.rs#encode fn L17-19 fn encode (order: & Order ) s:src/store.rs#checksum fn L22-24 fn checksum (text: & str ) # exit 0 · 280 bytes · ~80 est. tokens dctx map grep example -i exit 0 380 bytes ~109 est. tokens Exhaustive literal search. The .env value contains example too; it is never read, so it is not a hit. kiosk $ dctx map grep example -i # kiosk grep s:Cargo.toml#package.description fn Cargo.toml L5 : description = "A tiny order kiosk: the sample project for the dctx website examples." d:README.md#kiosk heading README.md L3 : A tiny order kiosk. It is the example project that every command on the dctx website runs on. s:config.toml#screen.title fn config.toml L2 : title = "kiosk example" 3 hits in 3 symbols # exit 0 · 380 bytes · ~109 est. tokens dctx map hubs --limit 10 exit 0 519 bytes ~149 est. tokens kiosk $ dctx map hubs --limit 10 # kiosk hubs s:src/store.rs#checksum fn src/store.rs 1 s:src/store.rs#encode fn src/store.rs 1 s:src/store.rs#save fn src/store.rs 1 s:src/util.rs#greet fn src/util.rs 1 s:src/util.rs#title_case fn src/util.rs 1 s:tools/report.py#main fn tools/report.py 1 s:tools/report.py#read_orders fn tools/report.py 1 s:web/format.ts#formatName fn web/format.ts 1 s:web/format.ts#formatPrice fn web/format.ts 1 ./ 4 files 12 symbols assets/ 1 files 0 symbols src/ 3 files 7 symbols tools/ 1 files 2 symbols web/ 2 files 5 symbols # exit 0 · 519 bytes · ~149 est. tokens dctx map path 's:src/main.rs#main' 's:src/store.rs#save' exit 0 99 bytes ~29 est. tokens kiosk $ dctx map path 's:src/main.rs#main' 's:src/store.rs#save' # kiosk path start s:src/main.rs#main fn src/main.rs calls:out s:src/store.rs#save fn src/store.rs # exit 0 · 99 bytes · ~29 est. tokens Map, JSON dctx map find greet --json exit 0 745 bytes ~213 est. tokens kiosk $ dctx map find greet --json # pretty-printed; the raw bytes are below { "v" : 2 , "place" : "kiosk" , "verb" : "find" , "freshness" : { "mode" : "strict" , "state" : "verified" }, "precision" : { "coverage" : "structural" , "completion" : "complete" , "parser" : "dctx-structural/3" }, "records" : [ { "id" : "s:src/util.rs#greet" , "kind" : "fn" , "path" : "src/util.rs" , "lines" : [ 2 , 4 ], "summary" : "The greeting shown on the kiosk screen." , "summary_source" : "doc" , "signature" : null , "span" : null , "source_utf8" : null , "edge" : null , "direction" : null , "target" : null , "confidence" : null }, { "id" : "s:web/app.ts#renderGreeting" , "kind" : "fn" , "path" : "web/app.ts" , "lines" : [ 10 , 12 ], "summary" : "The greeting banner of the kiosk web screen." , "summary_source" : "doc" , "signature" : null , "span" : null , "source_utf8" : null , "edge" : null , "direction" : null , "target" : null , "confidence" : null } ], "more" : 0 , "next" : null } # exit 0 · 745 bytes · ~213 est. tokens Raw output (745 bytes, as captured) { "v" : 2 , "place" : "kiosk" , "verb" : "find" , "freshness" :{ "mode" : "strict" , "state" : "verified" }, "precision" :{ "coverage" : "structural" , "completion" : "complete" , "parser" : "dctx-structural/3" }, "records" :[{ "id" : "s:src/util.rs#greet" , "kind" : "fn" , "path" : "src/util.rs" , "lines" :[ 2 , 4 ], "summary" : "The greeting shown on the kiosk screen." , "summary_source" : "doc" , "signature" : null , "span" : null , "source_utf8" : null , "edge" : null , "direction" : null , "target" : null , "confidence" : null },{ "id" : "s:web/app.ts#renderGreeting" , "kind" : "fn" , "path" : "web/app.ts" , "lines" :[ 10 , 12 ], "summary" : "The greeting banner of the kiosk web screen." , "summary_source" : "doc" , "signature" : null , "span" : null , "source_utf8" : null , "edge" : null , "direction" : null , "target" : null , "confidence" : null }], "more" : 0 , "next" : null } dctx map neighbors 's:src/util.rs#greet' --edge calls --dir in --json exit 0 365 bytes ~105 est. tokens kiosk $ dctx map neighbors 's:src/util.rs#greet' --edge calls --dir in --json # pretty-printed; the raw bytes are below { "v" : 2 , "place" : "kiosk" , "verb" : "neighbors" , "freshness" : { "mode" : "strict" , "state" : "verified" }, "precision" : { "coverage" : "structural" , "completion" : "complete" , "parser" : "dctx-structural/3" }, "records" : [ { "id" : "calls:in:s:src/main.rs#main" , "kind" : "fn" , "path" : "src/main.rs" , "lines" : [ 5 , 10 ], "edge" : "calls" , "direction" : "in" , "confidence" : "name" , "sites" : [ 7 ] } ], "more" : 0 , "next" : null } # exit 0 · 365 bytes · ~105 est. tokens Raw output (365 bytes, as captured) { "v" : 2 , "place" : "kiosk" , "verb" : "neighbors" , "freshness" :{ "mode" : "strict" , "state" : "verified" }, "precision" :{ "coverage" : "structural" , "completion" : "complete" , "parser" : "dctx-structural/3" }, "records" :[{ "id" : "calls:in:s:src/main.rs#main" , "kind" : "fn" , "path" : "src/main.rs" , "lines" :[ 5 , 10 ], "edge" : "calls" , "direction" : "in" , "confidence" : "name" , "sites" :[ 7 ]}], "more" : 0 , "next" : null } dctx map read 's:src/util.rs#greet' --json exit 0 561 bytes ~161 est. tokens The verified source bytes of one node. kiosk $ dctx map read 's:src/util.rs#greet' --json # pretty-printed; the raw bytes are below { "v" : 2 , "place" : "kiosk" , "verb" : "read" , "freshness" : { "mode" : "strict" , "state" : "verified" }, "precision" : { "coverage" : "syntax" , "completion" : "complete" , "parser" : "dctx-lex-rust/syn-3.0.9" }, "records" : [ { "id" : "s:src/util.rs#greet" , "kind" : "fn" , "path" : "src/util.rs" , "lines" : [ 2 , 4 ], "summary" : "The greeting shown on the kiosk screen." , "summary_source" : "doc" , "signature" : null , "span" : [ 44 , 126 ], "source_utf8" : "pub fn greet(name: &str) -> String {\n format!(\"Hello, {}!\", title_case(name))\n}" , "edge" : null , "direction" : null , "target" : null , "confidence" : null } ], "more" : 0 , "next" : null } # exit 0 · 561 bytes · ~161 est. tokens Raw output (561 bytes, as captured) { "v" : 2 , "place" : "kiosk" , "verb" : "read" , "freshness" :{ "mode" : "strict" , "state" : "verified" }, "precision" :{ "coverage" : "syntax" , "completion" : "complete" , "parser" : "dctx-lex-rust/syn-3.0.9" }, "records" :[{ "id" : "s:src/util.rs#greet" , "kind" : "fn" , "path" : "src/util.rs" , "lines" :[ 2 , 4 ], "summary" : "The greeting shown on the kiosk screen." , "summary_source" : "doc" , "signature" : null , "span" :[ 44 , 126 ], "source_utf8" : "pub fn greet(name: &str) -> String {\n format!(\"Hello, {}!\", title_case(name))\n}" , "edge" : null , "direction" : null , "target" : null , "confidence" : null }], "more" : 0 , "next" : null } dctx map find greet --json --meta exit 0 865 bytes ~248 est. tokens With --meta the answer also carries the snapshot digest, the generation and the index age. The age changes every second, which is why the default leaves these fields out; its digits are replaced with … here. kiosk $ dctx map find greet --json --meta { "v" : 2 , "place" : "kiosk" , "snapshot" : "v1:sha256:1de480dbf3f559eb25ca11d9bad2556f8239ae97916d084ce17abafb02916da3:6840" , "generation" : 1 , "verb" : "find" , "freshness" :{ "mode" : "strict" , "state" : "verified" , "age_s" :…}, "precision" :{ "coverage" : "structural" , "completion" : "complete" , "parser" : "dctx-structural/3" }, "records" :[{ "id" : "s:src/util.rs#greet" , "kind" : "fn" , "path" : "src/util.rs" , "lines" :[ 2 , 4 ], "summary" : "The greeting shown on the kiosk screen." , "summary_source" : "doc" , "signature" : null , "span" : null , "source_utf8" : null , "edge" : null , "direction" : null , "target" : null , "confidence" : null },{ "id" : "s:web/app.ts#renderGreeting" , "kind" : "fn" , "path" : "web/app.ts" , "lines" :[ 10 , 12 ], "summary" : "The greeting banner of the kiosk web screen." , "summary_source" : "doc" , "signature" : null , "span" : null , "source_utf8" : null , "edge" : null , "direction" : null , "target" : null , "confidence" : null }], "more" : 0 , "next" : null } # exit 0 · 865 bytes · ~248 est. tokens Graph export dctx map export --format mermaid exit 0 1,542 bytes ~441 est. tokens Paste into any Mermaid renderer. kiosk $ dctx map export --format mermaid flowchart LR n0 [ "d:README.md#Configuration" ] n1 [ "d:README.md#Orders" ] n2 [ "d:README.md#Run" ] n3 [ "d:README.md#kiosk" ] n4 [ "m:.gitignore" ] n5 [ "m:Cargo.toml" ] n6 [ "m:README.md" ] n7 [ "m:assets/logo.png" ] n8 [ "m:config.toml" ] n9 [ "m:src/main.rs" ] n10 [ "m:src/store.rs" ] n11 [ "m:src/util.rs" ] n12 [ "m:tools/report.py" ] n13 [ "m:web/app.ts" ] n14 [ "m:web/format.ts" ] n15 [ "s:Cargo.toml#dependencies" ] n16 [ "s:Cargo.toml#package" ] n17 [ "s:Cargo.toml#package.description" ] n18 [ "s:Cargo.toml#package.edition" ] n19 [ "s:Cargo.toml#package.license" ] n20 [ "s:Cargo.toml#package.name" ] n21 [ "s:Cargo.toml#package.version" ] n22 [ "s:config.toml#orders" ] n23 [ "s:config.toml#orders.folder" ] n24 [ "s:config.toml#screen" ] n25 [ "s:config.toml#screen.currency" ] n26 [ "s:config.toml#screen.title" ] n27 [ "s:src/main.rs#main" ] n28 [ "s:src/store.rs#Order" ] n29 [ "s:src/store.rs#checksum" ] n30 [ "s:src/store.rs#encode" ] n31 [ "s:src/store.rs#save" ] n32 [ "s:src/util.rs#greet" ] n33 [ "s:src/util.rs#title_case" ] n34 [ "s:tools/report.py#main" ] n35 [ "s:tools/report.py#read_orders" ] n36 [ "s:web/app.ts#Line" ] n37 [ "s:web/app.ts#renderGreeting" ] n38 [ "s:web/app.ts#renderReceipt" ] n39 [ "s:web/format.ts#formatName" ] n40 [ "s:web/format.ts#formatPrice" ] n9 --> |imports| n10 n9 --> |imports| n11 n12 --> |calls| n34 n13 --> |imports| n39 n13 --> |imports| n40 n27 --> |calls| n31 n27 --> |calls| n32 n30 --> |calls| n29 n31 --> |calls| n30 n32 --> |calls| n33 n34 --> |calls| n35 n37 --> |calls| n39 n38 --> |calls| n40 # exit 0 · 1,542 bytes · ~441 est. tokens dctx map export --format json exit 0 7,527 bytes ~2,151 est. tokens kiosk $ dctx map export --format json # pretty-printed; the raw bytes are below { "nodes" : [ { "id" : "d:README.md#Configuration" , "kind" : "heading" , "path" : "README.md" , "lines" : [ 16 , 18 ] }, { "id" : "d:README.md#Orders" , "kind" : "heading" , "path" : "README.md" , "lines" : [ 11 , 15 ] }, { "id" : "d:README.md#Run" , "kind" : "heading" , "path" : "README.md" , "lines" : [ 5 , 10 ] }, { "id" : "d:README.md#kiosk" , "kind" : "heading" , "path" : "README.md" , "lines" : [ 1 , 18 ] }, { "id" : "m:.gitignore" , "kind" : "module" , "path" : ".gitignore" , "lines" : [ 1 , 1 ] }, { "id" : "m:Cargo.toml" , "kind" : "module" , "path" : "Cargo.toml" , "lines" : [ 1 , 8 ] }, { "id" : "m:README.md" , "kind" : "module" , "path" : "README.md" , "lines" : [ 1 , 18 ] }, { "id" : "m:assets/logo.png" , "kind" : "module" , "path" : "assets/logo.png" , "lines" : [ 1 , 3 ] }, { "id" : "m:config.toml" , "kind" : "module" , "path" : "config.toml" , "lines" : [ 1 , 6 ] }, { "id" : "m:src/main.rs" , "kind" : "module" , "path" : "src/main.rs" , "lines" : [ 1 , 10 ] }, { "id" : "m:src/store.rs" , "kind" : "module" , "path" : "src/store.rs" , "lines" : [ 1 , 24 ] }, { "id" : "m:src/util.rs" , "kind" : "module" , "path" : "src/util.rs" , "lines" : [ 1 , 13 ] }, { "id" : "m:tools/report.py" , "kind" : "module" , "path" : "tools/report.py" , "lines" : [ 1 , 18 ] }, { "id" : "m:web/app.ts" , "kind" : "module" , "path" : "web/app.ts" , "lines" : [ 1 , 19 ] }, { "id" : "m:web/format.ts" , "kind" : "module" , "path" : "web/format.ts" , "lines" : [ 1 , 9 ] }, { "id" : "s:Cargo.toml#dependencies" , "kind" : "struct" , "path" : "Cargo.toml" , "lines" : [ 8 , 8 ] }, { "id" : "s:Cargo.toml#package" , "kind" : "struct" , "path" : "Cargo.toml" , "lines" : [ 1 , 6 ] }, { "id" : "s:Cargo.toml#package.description" , "kind" : "fn" , "path" : "Cargo.toml" , "lines" : [ 5 , 5 ] }, { "id" : "s:Cargo.toml#package.edition" , "kind" : "fn" , "path" : "Cargo.toml" , "lines" : [ 4 , 4 ] }, { "id" : "s:Cargo.toml#package.license" , "kind" : "fn" , "path" : "Cargo.toml" , "lines" : [ 6 , 6 ] }, { "id" : "s:Cargo.toml#package.name" , "kind" : "fn" , "path" : "Cargo.toml" , "lines" : [ 2 , 2 ] }, { "id" : "s:Cargo.toml#package.version" , "kind" : "fn" , "path" : "Cargo.toml" , "lines" : [ 3 , 3 ] }, { "id" : "s:config.toml#orders" , "kind" : "struct" , "path" : "config.toml" , "lines" : [ 5 , 6 ] }, { "id" : "s:config.toml#orders.folder" , "kind" : "fn" , "path" : "config.toml" , "lines" : [ 6 , 6 ] }, { "id" : "s:config.toml#screen" , "kind" : "struct" , "path" : "config.toml" , "lines" : [ 1 , 3 ] }, { "id" : "s:config.toml#screen.currency" , "kind" : "fn" , "path" : "config.toml" , "lines" : [ 3 , 3 ] }, { "id" : "s:config.toml#screen.title" , "kind" : "fn" , "path" : "config.toml" , "lines" : [ 2 , 2 ] }, { "id" : "s:src/main.rs#main" , "kind" : "fn" , "path" : "src/main.rs" , "lines" : [ 5 , 10 ] }, { "id" : "s:src/store.rs#Order" , "kind" : "struct" , "path" : "src/store.rs" , "lines" : [ 4 , 8 ] }, { "id" : "s:src/store.rs#checksum" , "kind" : "fn" , "path" : "src/store.rs" , "lines" : [ 22 , 24 ] }, { "id" : "s:src/store.rs#encode" , "kind" : "fn" , "path" : "src/store.rs" , "lines" : [ 17 , 19 ] }, { "id" : "s:src/store.rs#save" , "kind" : "fn" , "path" : "src/store.rs" , "lines" : [ 11 , 14 ] }, { "id" : "s:src/util.rs#greet" , "kind" : "fn" , "path" : "src/util.rs" , "lines" : [ 2 , 4 ] }, { "id" : "s:src/util.rs#title_case" , "kind" : "fn" , "path" : "src/util.rs" , "lines" : [ 7 , 13 ] }, { "id" : "s:tools/report.py#main" , "kind" : "fn" , "path" : "tools/report.py" , "lines" : [ 12 , 14 ] }, { "id" : "s:tools/report.py#read_orders" , "kind" : "fn" , "path" : "tools/report.py" , "lines" : [ 6 , 9 ] }, { "id" : "s:web/app.ts#Line" , "kind" : "interface" , "path" : "web/app.ts" , "lines" : [ 3 , 7 ] }, { "id" : "s:web/app.ts#renderGreeting" , "kind" : "fn" , "path" : "web/app.ts" , "lines" : [ 10 , 12 ] }, { "id" : "s:web/app.ts#renderReceipt" , "kind" : "fn" , "path" : "web/app.ts" , "lines" : [ 15 , 19 ] }, { "id" : "s:web/format.ts#formatName" , "kind" : "fn" , "path" : "web/format.ts" , "lines" : [ 7 , 9 ] }, { "id" : "s:web/format.ts#formatPrice" , "kind" : "fn" , "path" : "web/format.ts" , "lines" : [ 2 , 4 ] } ], "edges" : [ { "src" : "m:Cargo.toml" , "edge" : "contains" , "dst" : "s:Cargo.toml#dependencies" , "confidence" : "exact" }, { "src" : "m:Cargo.toml" , "edge" : "contains" , "dst" : "s:Cargo.toml#package" , "confidence" : "exact" }, { "src" : "m:Cargo.toml" , "edge" : "contains" , "dst" : "s:Cargo.toml#package.description" , "confidence" : "exact" }, { "src" : "m:Cargo.toml" , "edge" : "contains" , "dst" : "s:Cargo.toml#package.edition" , "confidence" : "exact" }, { "src" : "m:Cargo.toml" , "edge" : "contains" , "dst" : "s:Cargo.toml#package.license" , "confidence" : "exact" }, { "src" : "m:Cargo.toml" , "edge" : "contains" , "dst" : "s:Cargo.toml#package.name" , "confidence" : "exact" }, { "src" : "m:Cargo.toml" , "edge" : "contains" , "dst" : "s:Cargo.toml#package.version" , "confidence" : "exact" }, { "src" : "m:README.md" , "edge" : "contains" , "dst" : "d:README.md#Configuration" , "confidence" : "exact" }, { "src" : "m:README.md" , "edge" : "contains" , "dst" : "d:README.md#Orders" , "confidence" : "exact" }, { "src" : "m:README.md" , "edge" : "contains" , "dst" : "d:README.md#Run" , "confidence" : "exact" }, { "src" : "m:README.md" , "edge" : "contains" , "dst" : "d:README.md#kiosk" , "confidence" : "exact" }, { "src" : "m:config.toml" , "edge" : "contains" , "dst" : "s:config.toml#orders" , "confidence" : "exact" }, { "src" : "m:config.toml" , "edge" : "contains" , "dst" : "s:config.toml#orders.folder" , "confidence" : "exact" }, { "src" : "m:config.toml" , "edge" : "contains" , "dst" : "s:config.toml#screen" , "confidence" : "exact" }, { "src" : "m:config.toml" , "edge" : "contains" , "dst" : "s:config.toml#screen.currency" , "confidence" : "exact" }, { "src" : "m:config.toml" , "edge" : "contains" , "dst" : "s:config.toml#screen.title" , "confidence" : "exact" }, { "src" : "m:src/main.rs" , "edge" : "contains" , "dst" : "s:src/main.rs#main" , "confidence" : "exact" }, { "src" : "m:src/main.rs" , "edge" : "imports" , "dst" : "m:src/store.rs" , "confidence" : "exact" }, { "src" : "m:src/main.rs" , "edge" : "imports" , "dst" : "m:src/util.rs" , "confidence" : "exact" }, { "src" : "m:src/store.rs" , "edge" : "contains" , "dst" : "s:src/store.rs#Order" , "confidence" : "exact" }, { "src" : "m:src/store.rs" , "edge" : "contains" , "dst" : "s:src/store.rs#checksum" , "confidence" : "exact" }, { "src" : "m:src/store.rs" , "edge" : "contains" , "dst" : "s:src/store.rs#encode" , "confidence" : "exact" }, { "src" : "m:src/store.rs" , "edge" : "contains" , "dst" : "s:src/store.rs#save" , "confidence" : "exact" }, { "src" : "m:src/util.rs" , "edge" : "contains" , "dst" : "s:src/util.rs#greet" , "confidence" : "exact" }, { "src" : "m:src/util.rs" , "edge" : "contains" , "dst" : "s:src/util.rs#title_case" , "confidence" : "exact" }, { "src" : "m:tools/report.py" , "edge" : "calls" , "dst" : "s:tools/report.py#main" , "confidence" : "name" }, { "src" : "m:tools/report.py" , "edge" : "contains" , "dst" : "s:tools/report.py#main" , "confidence" : "exact" }, { "src" : "m:tools/report.py" , "edge" : "contains" , "dst" : "s:tools/report.py#read_orders" , "confidence" : "exact" }, { "src" : "m:web/app.ts" , "edge" : "contains" , "dst" : "s:web/app.ts#Line" , "confidence" : "exact" }, { "src" : "m:web/app.ts" , "edge" : "contains" , "dst" : "s:web/app.ts#renderGreeting" , "confidence" : "exact" }, { "src" : "m:web/app.ts" , "edge" : "contains" , "dst" : "s:web/app.ts#renderReceipt" , "confidence" : "exact" }, { "src" : "m:web/app.ts" , "edge" : "imports" , "dst" : "s:web/format.ts#formatName" , "confidence" : "exact" }, { "src" : "m:web/app.ts" , "edge" : "imports" , "dst" : "s:web/format.ts#formatPrice" , "confidence" : "exact" }, { "src" : "m:web/format.ts" , "edge" : "contains" , "dst" : "s:web/format.ts#formatName" , "confidence" : "exact" }, { "src" : "m:web/format.ts" , "edge" : "contains" , "dst" : "s:web/format.ts#formatPrice" , "confidence" : "exact" }, { "src" : "s:src/main.rs#main" , "edge" : "calls" , "dst" : "s:src/store.rs#save" , "confidence" : "name" }, { "src" : "s:src/main.rs#main" , "edge" : "calls" , "dst" : "s:src/util.rs#greet" , "confidence" : "name" }, { "src" : "s:src/store.rs#encode" , "edge" : "calls" , "dst" : "s:src/store.rs#checksum" , "confidence" : "name" }, { "src" : "s:src/store.rs#save" , "edge" : "calls" , "dst" : "s:src/store.rs#encode" , "confidence" : "name" }, { "src" : "s:src/util.rs#greet" , "edge" : "calls" , "dst" : "s:src/util.rs#title_case" , "confidence" : "name" }, { "src" : "s:tools/report.py#main" , "edge" : "calls" , "dst" : "s:tools/report.py#read_orders" , "confidence" : "name" }, { "src" : "s:web/app.ts#renderGreeting" , "edge" : "calls" , "dst" : "s:web/format.ts#formatName" , "confidence" : "name" }, { "src" : "s:web/app.ts#renderReceipt" , "edge" : "calls" , "dst" : "s:web/format.ts#formatPrice" , "confidence" : "name" } ] } # exit 0 · 7,527 bytes · ~2,151 est. tokens Raw output (7,527 bytes, as captured) { "nodes" :[ { "id" : "d:README.md#Configuration" , "kind" : "heading" , "path" : "README.md" , "lines" :[ 16 , 18 ]}, { "id" : "d:README.md#Orders" , "kind" : "heading" , "path" : "README.md" , "lines" :[ 11 , 15 ]}, { "id" : "d:README.md#Run" , "kind" : "heading" , "path" : "README.md" , "lines" :[ 5 , 10 ]}, { "id" : "d:README.md#kiosk" , "kind" : "heading" , "path" : "README.md" , "lines" :[ 1 , 18 ]}, { "id" : "m:.gitignore" , "kind" : "module" , "path" : ".gitignore" , "lines" :[ 1 , 1 ]}, { "id" : "m:Cargo.toml" , "kind" : "module" , "path" : "Cargo.toml" , "lines" :[ 1 , 8 ]}, { "id" : "m:README.md" , "kind" : "module" , "path" : "README.md" , "lines" :[ 1 , 18 ]}, { "id" : "m:assets/logo.png" , "kind" : "module" , "path" : "assets/logo.png" , "lines" :[ 1 , 3 ]}, { "id" : "m:config.toml" , "kind" : "module" , "path" : "config.toml" , "lines" :[ 1 , 6 ]}, { "id" : "m:src/main.rs" , "kind" : "module" , "path" : "src/main.rs" , "lines" :[ 1 , 10 ]}, { "id" : "m:src/store.rs" , "kind" : "module" , "path" : "src/store.rs" , "lines" :[ 1 , 24 ]}, { "id" : "m:src/util.rs" , "kind" : "module" , "path" : "src/util.rs" , "lines" :[ 1 , 13 ]}, { "id" : "m:tools/report.py" , "kind" : "module" , "path" : "tools/report.py" , "lines" :[ 1 , 18 ]}, { "id" : "m:web/app.ts" , "kind" : "module" , "path" : "web/app.ts" , "lines" :[ 1 , 19 ]}, { "id" : "m:web/format.ts" , "kind" : "module" , "path" : "web/format.ts" , "lines" :[ 1 , 9 ]}, { "id" : "s:Cargo.toml#dependencies" , "kind" : "struct" , "path" : "Cargo.toml" , "lines" :[ 8 , 8 ]}, { "id" : "s:Cargo.toml#package" , "kind" : "struct" , "path" : "Cargo.toml" , "lines" :[ 1 , 6 ]}, { "id" : "s:Cargo.toml#package.description" , "kind" : "fn" , "path" : "Cargo.toml" , "lines" :[ 5 , 5 ]}, { "id" : "s:Cargo.toml#package.edition" , "kind" : "fn" , "path" : "Cargo.toml" , "lines" :[ 4 , 4 ]}, { "id" : "s:Cargo.toml#package.license" , "kind" : "fn" , "path" : "Cargo.toml" , "lines" :[ 6 , 6 ]}, { "id" : "s:Cargo.toml#package.name" , "kind" : "fn" , "path" : "Cargo.toml" , "lines" :[ 2 , 2 ]}, { "id" : "s:Cargo.toml#package.version" , "kind" : "fn" , "path" : "Cargo.toml" , "lines" :[ 3 , 3 ]}, { "id" : "s:config.toml#orders" , "kind" : "struct" , "path" : "config.toml" , "lines" :[ 5 , 6 ]}, { "id" : "s:config.toml#orders.folder" , "kind" : "fn" , "path" : "config.toml" , "lines" :[ 6 , 6 ]}, { "id" : "s:config.toml#screen" , "kind" : "struct" , "path" : "config.toml" , "lines" :[ 1 , 3 ]}, { "id" : "s:config.toml#screen.currency" , "kind" : "fn" , "path" : "config.toml" , "lines" :[ 3 , 3 ]}, { "id" : "s:config.toml#screen.title" , "kind" : "fn" , "path" : "config.toml" , "lines" :[ 2 , 2 ]}, { "id" : "s:src/main.rs#main" , "kind" : "fn" , "path" : "src/main.rs" , "lines" :[ 5 , 10 ]}, { "id" : "s:src/store.rs#Order" , "kind" : "struct" , "path" : "src/store.rs" , "lines" :[ 4 , 8 ]}, { "id" : "s:src/store.rs#checksum" , "kind" : "fn" , "path" : "src/store.rs" , "lines" :[ 22 , 24 ]}, { "id" : "s:src/store.rs#encode" , "kind" : "fn" , "path" : "src/store.rs" , "lines" :[ 17 , 19 ]}, { "id" : "s:src/store.rs#save" , "kind" : "fn" , "path" : "src/store.rs" , "lines" :[ 11 , 14 ]}, { "id" : "s:src/util.rs#greet" , "kind" : "fn" , "path" : "src/util.rs" , "lines" :[ 2 , 4 ]}, { "id" : "s:src/util.rs#title_case" , "kind" : "fn" , "path" : "src/util.rs" , "lines" :[ 7 , 13 ]}, { "id" : "s:tools/report.py#main" , "kind" : "fn" , "path" : "tools/report.py" , "lines" :[ 12 , 14 ]}, { "id" : "s:tools/report.py#read_orders" , "kind" : "fn" , "path" : "tools/report.py" , "lines" :[ 6 , 9 ]}, { "id" : "s:web/app.ts#Line" , "kind" : "interface" , "path" : "web/app.ts" , "lines" :[ 3 , 7 ]}, { "id" : "s:web/app.ts#renderGreeting" , "kind" : "fn" , "path" : "web/app.ts" , "lines" :[ 10 , 12 ]}, { "id" : "s:web/app.ts#renderReceipt" , "kind" : "fn" , "path" : "web/app.ts" , "lines" :[ 15 , 19 ]}, { "id" : "s:web/format.ts#formatName" , "kind" : "fn" , "path" : "web/format.ts" , "lines" :[ 7 , 9 ]}, { "id" : "s:web/format.ts#formatPrice" , "kind" : "fn" , "path" : "web/format.ts" , "lines" :[ 2 , 4 ]}], "edges" :[ { "src" : "m:Cargo.toml" , "edge" : "contains" , "dst" : "s:Cargo.toml#dependencies" , "confidence" : "exact" }, { "src" : "m:Cargo.toml" , "edge" : "contains" , "dst" : "s:Cargo.toml#package" , "confidence" : "exact" }, { "src" : "m:Cargo.toml" , "edge" : "contains" , "dst" : "s:Cargo.toml#package.description" , "confidence" : "exact" }, { "src" : "m:Cargo.toml" , "edge" : "contains" , "dst" : "s:Cargo.toml#package.edition" , "confidence" : "exact" }, { "src" : "m:Cargo.toml" , "edge" : "contains" , "dst" : "s:Cargo.toml#package.license" , "confidence" : "exact" }, { "src" : "m:Cargo.toml" , "edge" : "contains" , "dst" : "s:Cargo.toml#package.name" , "confidence" : "exact" }, { "src" : "m:Cargo.toml" , "edge" : "contains" , "dst" : "s:Cargo.toml#package.version" , "confidence" : "exact" }, { "src" : "m:README.md" , "edge" : "contains" , "dst" : "d:README.md#Configuration" , "confidence" : "exact" }, { "src" : "m:README.md" , "edge" : "contains" , "dst" : "d:README.md#Orders" , "confidence" : "exact" }, { "src" : "m:README.md" , "edge" : "contains" , "dst" : "d:README.md#Run" , "confidence" : "exact" }, { "src" : "m:README.md" , "edge" : "contains" , "dst" : "d:README.md#kiosk" , "confidence" : "exact" }, { "src" : "m:config.toml" , "edge" : "contains" , "dst" : "s:config.toml#orders" , "confidence" : "exact" }, { "src" : "m:config.toml" , "edge" : "contains" , "dst" : "s:config.toml#orders.folder" , "confidence" : "exact" }, { "src" : "m:config.toml" , "edge" : "contains" , "dst" : "s:config.toml#screen" , "confidence" : "exact" }, { "src" : "m:config.toml" , "edge" : "contains" , "dst" : "s:config.toml#screen.currency" , "confidence" : "exact" }, { "src" : "m:config.toml" , "edge" : "contains" , "dst" : "s:config.toml#screen.title" , "confidence" : "exact" }, { "src" : "m:src/main.rs" , "edge" : "contains" , "dst" : "s:src/main.rs#main" , "confidence" : "exact" }, { "src" : "m:src/main.rs" , "edge" : "imports" , "dst" : "m:src/store.rs" , "confidence" : "exact" }, { "src" : "m:src/main.rs" , "edge" : "imports" , "dst" : "m:src/util.rs" , "confidence" : "exact" }, { "src" : "m:src/store.rs" , "edge" : "contains" , "dst" : "s:src/store.rs#Order" , "confidence" : "exact" }, { "src" : "m:src/store.rs" , "edge" : "contains" , "dst" : "s:src/store.rs#checksum" , "confidence" : "exact" }, { "src" : "m:src/store.rs" , "edge" : "contains" , "dst" : "s:src/store.rs#encode" , "confidence" : "exact" }, { "src" : "m:src/store.rs" , "edge" : "contains" , "dst" : "s:src/store.rs#save" , "confidence" : "exact" }, { "src" : "m:src/util.rs" , "edge" : "contains" , "dst" : "s:src/util.rs#greet" , "confidence" : "exact" }, { "src" : "m:src/util.rs" , "edge" : "contains" , "dst" : "s:src/util.rs#title_case" , "confidence" : "exact" }, { "src" : "m:tools/report.py" , "edge" : "calls" , "dst" : "s:tools/report.py#main" , "confidence" : "name" }, { "src" : "m:tools/report.py" , "edge" : "contains" , "dst" : "s:tools/report.py#main" , "confidence" : "exact" }, { "src" : "m:tools/report.py" , "edge" : "contains" , "dst" : "s:tools/report.py#read_orders" , "confidence" : "exact" }, { "src" : "m:web/app.ts" , "edge" : "contains" , "dst" : "s:web/app.ts#Line" , "confidence" : "exact" }, { "src" : "m:web/app.ts" , "edge" : "contains" , "dst" : "s:web/app.ts#renderGreeting" , "confidence" : "exact" }, { "src" : "m:web/app.ts" , "edge" : "contains" , "dst" : "s:web/app.ts#renderReceipt" , "confidence" : "exact" }, { "src" : "m:web/app.ts" , "edge" : "imports" , "dst" : "s:web/format.ts#formatName" , "confidence" : "exact" }, { "src" : "m:web/app.ts" , "edge" : "imports" , "dst" : "s:web/format.ts#formatPrice" , "confidence" : "exact" }, { "src" : "m:web/format.ts" , "edge" : "contains" , "dst" : "s:web/format.ts#formatName" , "confidence" : "exact" }, { "src" : "m:web/format.ts" , "edge" : "contains" , "dst" : "s:web/format.ts#formatPrice" , "confidence" : "exact" }, { "src" : "s:src/main.rs#main" , "edge" : "calls" , "dst" : "s:src/store.rs#save" , "confidence" : "name" }, { "src" : "s:src/main.rs#main" , "edge" : "calls" , "dst" : "s:src/util.rs#greet" , "confidence" : "name" }, { "src" : "s:src/store.rs#encode" , "edge" : "calls" , "dst" : "s:src/store.rs#checksum" , "confidence" : "name" }, { "src" : "s:src/store.rs#save" , "edge" : "calls" , "dst" : "s:src/store.rs#encode" , "confidence" : "name" }, { "src" : "s:src/util.rs#greet" , "edge" : "calls" , "dst" : "s:src/util.rs#title_case" , "confidence" : "name" }, { "src" : "s:tools/report.py#main" , "edge" : "calls" , "dst" : "s:tools/report.py#read_orders" , "confidence" : "name" }, { "src" : "s:web/app.ts#renderGreeting" , "edge" : "calls" , "dst" : "s:web/format.ts#formatName" , "confidence" : "name" }, { "src" : "s:web/app.ts#renderReceipt" , "edge" : "calls" , "dst" : "s:web/format.ts#formatPrice" , "confidence" : "name" }]} Errors and exit codes dctx map read m:nope.rs exit 1 28 bytes ~8 est. tokens An id that is not in the index: the gone page on stdout, exit 1, two lines on stderr. kiosk $ dctx map read m:nope.rs # kiosk read gone m:nope.rs [no] Error: map: m:nope.rs is not in the index hint: the file may be missing, ignored, sensitive or renamed; list current ids with `dctx map find <name>` # exit 1 · 28 bytes · ~8 est. tokens dctx map read m:.env exit 1 25 bytes ~8 est. tokens A sensitive file is not in the index at all. kiosk $ dctx map read m:.env # kiosk read gone m:.env [no] Error: map: m:.env is not in the index hint: the file may be missing, ignored, sensitive or renamed; list current ids with `dctx map find <name>` # exit 1 · 25 bytes · ~8 est. tokens dctx map find '' exit 2 0 bytes ~0 est. tokens An empty query is a usage error, exit 2. kiosk $ dctx map find '' [no] Error: map: this verb requires a target; next: correct the request or source input and retry; use dctx map --help for options hint: pass a non-empty name or phrase, for example: dctx map find alpha # exit 2 · 0 bytes · ~0 est. tokens --- url: https://www.dctx.internet.technology/templates/ title: Templates source: https://www.dctx.internet.technology/templates/ --- Templates Templates The dctx Template System (DTS) defines the text dctx pack prints. dctx 1.3.1 ships two built-in templates; both are shown here with their real output on the sample project. Which template pack uses dctx pack renders the default template; --tree-stamps=on selects the stamped one, the 1.0.0 text. legacy_output.rs dctx template build <PATH> parses and validates a template file and prints its compiled plan; with --output PATH it writes the plan. dctx template list lists explicit compiled plans. The 1.1.0 pack command has no option that selects a compiled plan, so this page shows no third, custom template. dctx template build $ dctx template build default.dctx_template template source_version = 1 plan_bytes = 2191 digest = 5fdd4d1fd3ef127241bc661a6057dad7cf812b0081eec51e58b2bf09f3b802fb views = 1 retention = stdout # exit 0 · 139 bytes · ~40 est. tokens $ dctx template build stamped.dctx_template template source_version = 1 plan_bytes = 2243 digest = e55e481eef9bec67a82232802068e28037389d0bdd1efbce5e3dcda73a327364 views = 1 retention = stdout # exit 0 · 139 bytes · ~40 est. tokens What changes between them This file defines how the LLM context is formatted. The only difference is the tree entry and its instruction line: the default leaves out MOD and SIZE , because a timestamp changes on a bare touch and a size on every edit, and either breaks the byte-stable prefix a prompt cache reuses. The tree of the sample, word by word ( default to stamped ; the MOD digits are replaced with … since they are file times): DIRECTORY_TREE: pack . -> pack . --tree-stamps=on [D] (ID:ROOT) (ID:ROOT, MOD:…) [F] .env (ID:F001) (ID:F001, MOD:…, SIZE:29) [F] .gitignore (ID:F002) (ID:F002, MOD:…, SIZE:8) [F] Cargo.toml (ID:F003) (ID:F003, MOD:…, SIZE:185) [F] README.md (ID:F004) (ID:F004, MOD:…, SIZE:473) [F] config.toml (ID:F005) (ID:F005, MOD:…, SIZE:78) [D] src (ID:D006) (ID:D006, MOD:…) [F] src/main.rs (ID:F007) (ID:F007, MOD:…, SIZE:331) [F] src/store.rs (ID:F008) (ID:F008, MOD:…, SIZE:698) [F] src/util.rs (ID:F009) (ID:F009, MOD:…, SIZE:404) [D] tools (ID:D010) (ID:D010, MOD:…) [F] tools/report.py (ID:F011) (ID:F011, MOD:…, SIZE:484) [D] web (ID:D012) (ID:D012, MOD:…) [F] web/app.ts (ID:F013) (ID:F013, MOD:…, SIZE:596) [F] web/format.ts (ID:F014) (ID:F014, MOD:…, SIZE:350) default.dctx_template crates/dctx-template/templates/default.dctx_template source Copy # ============================================================================== # DCTX TEMPLATE DEFINITION V1 # ============================================================================== # This file defines how the LLM context is formatted. # It consists of three sections: [VARIABLES], [PARTIALS], and [LAYOUT]. # # SYNTAX GUIDE: # - {{VAR_NAME}} : Inserts a configuration variable defined in [VARIABLES]. # - {{{DATA_FIELD}}} : Inserts dynamic data from the project (e.g., file content). # # ============================================================================== [VARIABLES] # --- 1. Syntactic Markers (Granular Control) --- # Defines the exact characters used to wrap tags. # Allows handling XML, HTML, or Custom formats safely. start_marker_open = "<" start_marker_close = ">" end_marker_open = "</" end_marker_close = ">" # --- 2. Semantic Marker Names --- # Defines the keywords used inside the tags. instr_marker = "INSTRUCTIONS" tree_start_marker = "DIRECTORY_TREE" tree_end_marker = "DIRECTORY_TREE" file_start_marker = "FILE_CONTENT_START" file_end_marker = "FILE_CONTENT_END" # --- 3. Attribute Keys --- # Used inside tags to denote properties. attr_id = "ID" attr_path = "PATH" attr_size = "SIZE" attr_lines = "LINES" attr_mod = "MOD" # --- 4. Branding & Header Config --- folder_denotation_marker = "DIRECTORY" # --- 5. Instructions Block Text --- # This text explains the format to the LLM. It references the variables above # to ensure the instructions always match the actual format used. # Use '\n' for new lines. instructions_text = "1. Manifest: The {{start_marker_open}} {{tree_start_marker}} {{start_marker_close}} section lists all files. \n - Each entry: [TYPE] RELATIVE_PATH ( {{attr_id}} :UNIQUE_ID) \n - TYPE is [D] for directory, [F] for file. \n 2. Content Access: To read a specific file: \n - Find its UNIQUE_ID from the directory tree. \n - Search for the marker: {{start_marker_open}} {{file_start_marker}} {{attr_id}} =" UNIQUE_ID " {{start_marker_close}} \n - The content is between this marker and {{end_marker_open}} {{file_end_marker}} {{attr_id}} =" UNIQUE_ID " {{end_marker_close}} " # ============================================================================== # [PARTIALS] # Defines the look of repeated elements (Tree items and Files). # ============================================================================== # --- Tree Entry Partial --- # Context: 'node' object # Available Data: {{{node.type_char}}}, {{{node.path}}}, {{{node.id}}}, {{{node.mod}}}, {{{node.size}}} # The default entry leaves {{{node.mod}}} and {{{node.size_part}}} out: a timestamp or a size changes on an edit or a touch # and would break the byte-stable prefix of the page. Custom templates may still use {{attr_mod}}, {{{node.mod}}}, # {{{node.size}}} and {{{node.size_part}}}; `--tree-stamps=on` selects the stamped built-in (the 1.0.0 text). [PARTIAL:TREE_ENTRY] {{{node.type_char}}} {{{node.path}}} ( {{attr_id}} : {{{node.id}}} ) # --- File Block Partial --- # Context: 'file' object # Available Data: {{{file.id}}}, {{{file.path}}}, {{{file.lines}}}, {{{file.size}}}, {{{file.content}}} [PARTIAL:FILE_BLOCK] {{start_marker_open}} {{file_start_marker}} {{attr_id}} = " {{{file.id}}} " {{attr_path}} = " {{{file.path}}} " {{attr_lines}} = " {{{file.lines}}} " {{start_marker_close}} {{{file.content}}} {{end_marker_open}} {{file_end_marker}} {{attr_id}} = " {{{file.id}}} " {{end_marker_close}} # ============================================================================== # [LAYOUT] # The master structure of the final output file. # Note: The Version Header (e.g. [DCTX_SNAPSHOT_V1]) is hardcoded in the binary # and NOT included here. # ============================================================================== [LAYOUT] [ {{folder_denotation_marker}} : {{{project}}} ] {{start_marker_open}} {{instr_marker}} {{start_marker_close}} {{instructions_text}} {{end_marker_open}} {{instr_marker}} {{end_marker_close}} {{start_marker_open}} {{tree_start_marker}} {{start_marker_close}} {{{comp.tree}}} {{end_marker_open}} {{tree_end_marker}} {{end_marker_close}} {{{comp.files}}} Output: dctx pack . kiosk $ dctx pack . [DCTX_LLM_CONTEXT_SNAPSHOT_V1] [DIRECTORY:kiosk] <INSTRUCTIONS > 1. Manifest: The <DIRECTORY_TREE > section lists all files. - Each entry: [TYPE] RELATIVE_PATH (ID:UNIQUE_ID) - TYPE is [D] for directory, [F] for file. 2. Content Access: To read a specific file: - Find its UNIQUE_ID from the directory tree. - Search for the marker: <FILE_CONTENT_START ID = "UNIQUE_ID" > - The content is between this marker and </FILE_CONTENT_END ID = "UNIQUE_ID" > </INSTRUCTIONS > <DIRECTORY_TREE > [D] (ID:ROOT) [F] .env (ID:F001) [F] .gitignore (ID:F002) [F] Cargo.toml (ID:F003) [F] README.md (ID:F004) [F] config.toml (ID:F005) [D] src (ID:D006) [F] src/main.rs (ID:F007) [F] src/store.rs (ID:F008) [F] src/util.rs (ID:F009) [D] tools (ID:D010) [F] tools/report.py (ID:F011) [D] web (ID:D012) [F] web/app.ts (ID:F013) [F] web/format.ts (ID:F014) </DIRECTORY_TREE > <FILE_CONTENT_START ID = "F001" PATH = ".env" LINES = "0" > [Content omitted by pattern rules] </FILE_CONTENT_END ID = "F001" > <FILE_CONTENT_START ID = "F002" PATH = ".gitignore" LINES = "2" > target / </FILE_CONTENT_END ID = "F002" > <FILE_CONTENT_START ID = "F003" PATH = "Cargo.toml" LINES = "9" > [package] name = "kiosk" version = "0.1.0" edition = "2021" description = "A tiny order kiosk: the sample project for the dctx website examples." license = "Apache-2.0" [dependencies] </FILE_CONTENT_END ID = "F003" > <FILE_CONTENT_START ID = "F004" PATH = "README.md" LINES = "19" > # kiosk A tiny order kiosk. It is the example project that every command on the dctx website runs on. ## Run cargo run -- ada prints `Hello, Ada!` and saves order 1 to `orders/1.tsv` . ## Orders Each order is one tab-separated line: id, item, quantity and a checksum of the item name. `python3 tools/report.py orders/` sums the quantities. ## Configuration `config.toml` holds the currency and the screen title. Secrets live in `.env` , which is never committed. </FILE_CONTENT_END ID = "F004" > <FILE_CONTENT_START ID = "F005" PATH = "config.toml" LINES = "7" > [screen] title = "kiosk example" currency = "EUR" [orders] folder = "orders" </FILE_CONTENT_END ID = "F005" > <FILE_CONTENT_START ID = "F007" PATH = "src/main.rs" LINES = "11" > //! kiosk: greet a customer, take one order, save it. mod store ; mod util ; fn main () { let name = std::env:: args (). nth ( 1 ). unwrap_or_else (|| "guest" . to_string ()); println! ( "{}" , util:: greet (&name)); let order = store:: Order { id: 1 , item: "coffee" . to_string (), qty: 2 }; store:: save (&order). expect ( "save order" ); } </FILE_CONTENT_END ID = "F007" > <FILE_CONTENT_START ID = "F008" PATH = "src/store.rs" LINES = "25" > use std::io; /// One order as the kiosk records it. pub struct Order { pub id: u32 , pub item: String , pub qty: u32 , } /// Write the order to orders/<id>.tsv. pub fn save (order: & Order ) -> io:: Result <()> { std::fs:: create_dir_all ( "orders" )?; std::fs:: write ( format! ( "orders/{}.tsv" , order.id), encode (order)) } /// One tab-separated line with a checksum of the item name. fn encode (order: & Order ) -> String { format! ( "{}\t{}\t{}\t{:08x}\n" , order.id, order.item, order.qty, checksum (&order.item)) } /// FNV-1a over the bytes of the text. fn checksum (text: & str ) -> u32 { text. bytes (). fold ( 0x811c9dc5 , |hash, byte| (hash ^ u32 :: from (byte)). wrapping_mul ( 0x0100_0193 )) } </FILE_CONTENT_END ID = "F008" > <FILE_CONTENT_START ID = "F009" PATH = "src/util.rs" LINES = "14" > /// The greeting shown on the kiosk screen. pub fn greet (name: & str ) -> String { format! ( "Hello, {}!" , title_case (name)) } /// Upper-case the first letter of a name, leave the rest as typed. pub fn title_case (name: & str ) -> String { let mut chars = name. chars (); match chars. next () { Some (first) => first. to_uppercase (). chain (chars). collect (), None => String :: new (), } } </FILE_CONTENT_END ID = "F009" > <FILE_CONTENT_START ID = "F011" PATH = "tools/report.py" LINES = "19" > """Sum the quantities of every saved order: python3 tools/report.py orders/""" import sys from pathlib import Path def read_orders (folder): for path in sorted ( Path (folder). glob ( "*.tsv" )): order_id, item, qty, _checksum = path. read_text (). rstrip ( "\n" ). split ( "\t" ) yield order_id, item, int (qty) def main (folder= "orders" ): total = sum (qty for _, _, qty in read_orders (folder)) print ( f"{total} items" ) if __name__ == "__main__" : main (*sys.argv[ 1 :]) </FILE_CONTENT_END ID = "F011" > <FILE_CONTENT_START ID = "F013" PATH = "web/app.ts" LINES = "20" > import { formatName, formatPrice } from "./format" ; interface Line { item: string ; cents: number ; qty: number ; } /** The greeting banner of the kiosk web screen. */ export function renderGreeting (name: string ): string { return `Hello, ${formatName(name)}!` ; } /** One receipt line per order line, then the total. */ export function renderReceipt (lines: Line []): string [] { const rows = lines. map ((l) => `${l.qty} x ${l.item} ${formatPrice(l.cents * l.qty)}` ); const total = lines. reduce ((sum, l) => sum + l.cents * l.qty, 0 ); return [...rows, `total ${formatPrice(total)}` ]; } </FILE_CONTENT_END ID = "F013" > <FILE_CONTENT_START ID = "F014" PATH = "web/format.ts" LINES = "10" > /** Price in cents to a display string, e.g. 250 -> "2.50 EUR". */ export function formatPrice (cents: number , currency = "EUR" ): string { return `${(cents / 100).toFixed(2)} ${currency}` ; } /** The customer's name as the screen shows it. */ export function formatName (name: string ): string { return name. trim () === "" ? "guest" : name. trim (); } </FILE_CONTENT_END ID = "F014" > pack bytes=5545 files=11 retention=stdout version=V1 # exit 0 · 5,545 bytes · ~1,585 est. tokens stamped.dctx_template crates/dctx-template/templates/stamped.dctx_template source Copy # ============================================================================== # DCTX TEMPLATE DEFINITION V1 # ============================================================================== # This file defines how the LLM context is formatted. # It consists of three sections: [VARIABLES], [PARTIALS], and [LAYOUT]. # # SYNTAX GUIDE: # - {{VAR_NAME}} : Inserts a configuration variable defined in [VARIABLES]. # - {{{DATA_FIELD}}} : Inserts dynamic data from the project (e.g., file content). # # ============================================================================== [VARIABLES] # --- 1. Syntactic Markers (Granular Control) --- # Defines the exact characters used to wrap tags. # Allows handling XML, HTML, or Custom formats safely. start_marker_open = "<" start_marker_close = ">" end_marker_open = "</" end_marker_close = ">" # --- 2. Semantic Marker Names --- # Defines the keywords used inside the tags. instr_marker = "INSTRUCTIONS" tree_start_marker = "DIRECTORY_TREE" tree_end_marker = "DIRECTORY_TREE" file_start_marker = "FILE_CONTENT_START" file_end_marker = "FILE_CONTENT_END" # --- 3. Attribute Keys --- # Used inside tags to denote properties. attr_id = "ID" attr_path = "PATH" attr_size = "SIZE" attr_lines = "LINES" attr_mod = "MOD" # --- 4. Branding & Header Config --- folder_denotation_marker = "DIRECTORY" # --- 5. Instructions Block Text --- # This text explains the format to the LLM. It references the variables above # to ensure the instructions always match the actual format used. # Use '\n' for new lines. instructions_text = "1. Manifest: The {{start_marker_open}} {{tree_start_marker}} {{start_marker_close}} section lists all files. \n - Each entry: [TYPE] RELATIVE_PATH ( {{attr_id}} :UNIQUE_ID, {{attr_mod}} :TIMESTAMP) \n - TYPE is [D] for directory, [F] for file. \n 2. Content Access: To read a specific file: \n - Find its UNIQUE_ID from the directory tree. \n - Search for the marker: {{start_marker_open}} {{file_start_marker}} {{attr_id}} =" UNIQUE_ID " {{start_marker_close}} \n - The content is between this marker and {{end_marker_open}} {{file_end_marker}} {{attr_id}} =" UNIQUE_ID " {{end_marker_close}} " # ============================================================================== # [PARTIALS] # Defines the look of repeated elements (Tree items and Files). # ============================================================================== # --- Tree Entry Partial --- # Context: 'node' object # Available Data: {{{node.type_char}}}, {{{node.path}}}, {{{node.id}}}, {{{node.mod}}}, {{{node.size}}} [PARTIAL:TREE_ENTRY] {{{node.type_char}}} {{{node.path}}} ( {{attr_id}} : {{{node.id}}} , {{attr_mod}} : {{{node.mod}}} {{{node.size_part}}} ) # --- File Block Partial --- # Context: 'file' object # Available Data: {{{file.id}}}, {{{file.path}}}, {{{file.lines}}}, {{{file.size}}}, {{{file.content}}} [PARTIAL:FILE_BLOCK] {{start_marker_open}} {{file_start_marker}} {{attr_id}} = " {{{file.id}}} " {{attr_path}} = " {{{file.path}}} " {{attr_lines}} = " {{{file.lines}}} " {{start_marker_close}} {{{file.content}}} {{end_marker_open}} {{file_end_marker}} {{attr_id}} = " {{{file.id}}} " {{end_marker_close}} # ============================================================================== # [LAYOUT] # The master structure of the final output file. # Note: The Version Header (e.g. [DCTX_SNAPSHOT_V1]) is hardcoded in the binary # and NOT included here. # ============================================================================== [LAYOUT] [ {{folder_denotation_marker}} : {{{project}}} ] {{start_marker_open}} {{instr_marker}} {{start_marker_close}} {{instructions_text}} {{end_marker_open}} {{instr_marker}} {{end_marker_close}} {{start_marker_open}} {{tree_start_marker}} {{start_marker_close}} {{{comp.tree}}} {{end_marker_open}} {{tree_end_marker}} {{end_marker_close}} {{{comp.files}}} Output: dctx pack . --tree-stamps=on kiosk $ dctx pack . --tree-stamps= on [DCTX_LLM_CONTEXT_SNAPSHOT_V1] [DIRECTORY:kiosk] <INSTRUCTIONS > 1. Manifest: The <DIRECTORY_TREE > section lists all files. - Each entry: [TYPE] RELATIVE_PATH (ID:UNIQUE_ID, MOD:TIMESTAMP) - TYPE is [D] for directory, [F] for file. 2. Content Access: To read a specific file: - Find its UNIQUE_ID from the directory tree. - Search for the marker: <FILE_CONTENT_START ID = "UNIQUE_ID" > - The content is between this marker and </FILE_CONTENT_END ID = "UNIQUE_ID" > </INSTRUCTIONS > <DIRECTORY_TREE > [D] (ID:ROOT, MOD:…) [F] .env (ID:F001, MOD:…, SIZE:29) [F] .gitignore (ID:F002, MOD:…, SIZE:8) [F] Cargo.toml (ID:F003, MOD:…, SIZE:185) [F] README.md (ID:F004, MOD:…, SIZE:473) [F] config.toml (ID:F005, MOD:…, SIZE:78) [D] src (ID:D006, MOD:…) [F] src/main.rs (ID:F007, MOD:…, SIZE:331) [F] src/store.rs (ID:F008, MOD:…, SIZE:698) [F] src/util.rs (ID:F009, MOD:…, SIZE:404) [D] tools (ID:D010, MOD:…) [F] tools/report.py (ID:F011, MOD:…, SIZE:484) [D] web (ID:D012, MOD:…) [F] web/app.ts (ID:F013, MOD:…, SIZE:596) [F] web/format.ts (ID:F014, MOD:…, SIZE:350) </DIRECTORY_TREE > <FILE_CONTENT_START ID = "F001" PATH = ".env" LINES = "0" > [Content omitted by pattern rules] </FILE_CONTENT_END ID = "F001" > <FILE_CONTENT_START ID = "F002" PATH = ".gitignore" LINES = "2" > target / </FILE_CONTENT_END ID = "F002" > <FILE_CONTENT_START ID = "F003" PATH = "Cargo.toml" LINES = "9" > [package] name = "kiosk" version = "0.1.0" edition = "2021" description = "A tiny order kiosk: the sample project for the dctx website examples." license = "Apache-2.0" [dependencies] </FILE_CONTENT_END ID = "F003" > <FILE_CONTENT_START ID = "F004" PATH = "README.md" LINES = "19" > # kiosk A tiny order kiosk. It is the example project that every command on the dctx website runs on. ## Run cargo run -- ada prints `Hello, Ada!` and saves order 1 to `orders/1.tsv` . ## Orders Each order is one tab-separated line: id, item, quantity and a checksum of the item name. `python3 tools/report.py orders/` sums the quantities. ## Configuration `config.toml` holds the currency and the screen title. Secrets live in `.env` , which is never committed. </FILE_CONTENT_END ID = "F004" > <FILE_CONTENT_START ID = "F005" PATH = "config.toml" LINES = "7" > [screen] title = "kiosk example" currency = "EUR" [orders] folder = "orders" </FILE_CONTENT_END ID = "F005" > <FILE_CONTENT_START ID = "F007" PATH = "src/main.rs" LINES = "11" > //! kiosk: greet a customer, take one order, save it. mod store ; mod util ; fn main () { let name = std::env:: args (). nth ( 1 ). unwrap_or_else (|| "guest" . to_string ()); println! ( "{}" , util:: greet (&name)); let order = store:: Order { id: 1 , item: "coffee" . to_string (), qty: 2 }; store:: save (&order). expect ( "save order" ); } </FILE_CONTENT_END ID = "F007" > <FILE_CONTENT_START ID = "F008" PATH = "src/store.rs" LINES = "25" > use std::io; /// One order as the kiosk records it. pub struct Order { pub id: u32 , pub item: String , pub qty: u32 , } /// Write the order to orders/<id>.tsv. pub fn save (order: & Order ) -> io:: Result <()> { std::fs:: create_dir_all ( "orders" )?; std::fs:: write ( format! ( "orders/{}.tsv" , order.id), encode (order)) } /// One tab-separated line with a checksum of the item name. fn encode (order: & Order ) -> String { format! ( "{}\t{}\t{}\t{:08x}\n" , order.id, order.item, order.qty, checksum (&order.item)) } /// FNV-1a over the bytes of the text. fn checksum (text: & str ) -> u32 { text. bytes (). fold ( 0x811c9dc5 , |hash, byte| (hash ^ u32 :: from (byte)). wrapping_mul ( 0x0100_0193 )) } </FILE_CONTENT_END ID = "F008" > <FILE_CONTENT_START ID = "F009" PATH = "src/util.rs" LINES = "14" > /// The greeting shown on the kiosk screen. pub fn greet (name: & str ) -> String { format! ( "Hello, {}!" , title_case (name)) } /// Upper-case the first letter of a name, leave the rest as typed. pub fn title_case (name: & str ) -> String { let mut chars = name. chars (); match chars. next () { Some (first) => first. to_uppercase (). chain (chars). collect (), None => String :: new (), } } </FILE_CONTENT_END ID = "F009" > <FILE_CONTENT_START ID = "F011" PATH = "tools/report.py" LINES = "19" > """Sum the quantities of every saved order: python3 tools/report.py orders/""" import sys from pathlib import Path def read_orders (folder): for path in sorted ( Path (folder). glob ( "*.tsv" )): order_id, item, qty, _checksum = path. read_text (). rstrip ( "\n" ). split ( "\t" ) yield order_id, item, int (qty) def main (folder= "orders" ): total = sum (qty for _, _, qty in read_orders (folder)) print ( f"{total} items" ) if __name__ == "__main__" : main (*sys.argv[ 1 :]) </FILE_CONTENT_END ID = "F011" > <FILE_CONTENT_START ID = "F013" PATH = "web/app.ts" LINES = "20" > import { formatName, formatPrice } from "./format" ; interface Line { item: string ; cents: number ; qty: number ; } /** The greeting banner of the kiosk web screen. */ export function renderGreeting (name: string ): string { return `Hello, ${formatName(name)}!` ; } /** One receipt line per order line, then the total. */ export function renderReceipt (lines: Line []): string [] { const rows = lines. map ((l) => `${l.qty} x ${l.item} ${formatPrice(l.cents * l.qty)}` ); const total = lines. reduce ((sum, l) => sum + l.cents * l.qty, 0 ); return [...rows, `total ${formatPrice(total)}` ]; } </FILE_CONTENT_END ID = "F013" > <FILE_CONTENT_START ID = "F014" PATH = "web/format.ts" LINES = "10" > /** Price in cents to a display string, e.g. 250 -> "2.50 EUR". */ export function formatPrice (cents: number , currency = "EUR" ): string { return `${(cents / 100).toFixed(2)} ${currency}` ; } /** The customer's name as the screen shows it. */ export function formatName (name: string ): string { return name. trim () === "" ? "guest" : name. trim (); } </FILE_CONTENT_END ID = "F014" > pack bytes=5951 files=11 retention=stdout version=V1 # exit 0 · 5,801 bytes · ~1,658 est. tokens Syntax From ADR-003 , sections 1, 3, 4 and 5. The contract of the source and the compiled plan is DTS v2 . 1. Decision: Explicit Marker Definition # To ensure future compatibility with non-HTML-like syntax, the templating language separates "Opening" and "Closing" logic for tags into four distinct definitions: * start_marker_open (Default: < ) * start_marker_close (Default: > ) * end_marker_open (Default: </ ) * end_marker_close (Default: > ) This allows users to redefine tags completely, e.g., to [SECTION] ... [/SECTION] or {{#SECTION}} ... {{/SECTION}} . 3. Decision: Two-Pass Rendering Engine # The rendering engine operates in two distinct passes to separate Configuration from Data. Pass 1 (Config Resolution): Occurs during the "Template Build" phase. Resolves all {{VAR}} placeholders within the [VARIABLES] section. Pass 2 (Data Injection): Occurs during runtime. Injects {{{DATA}}} into the pre-compiled Partial structures ( [PARTIALS] section) and assembles the [LAYOUT] . 4. Template File Structure # The file format uses a custom INI-like syntax with three specific sections: 1. [VARIABLES]: Key-Value pairs for static strings. 2. [PARTIALS]: Definitions for repeated elements ( TREE_ENTRY , FILE_BLOCK ). 3. [LAYOUT]: The global document structure. 5. Available Data Variables (Runtime) # These variables are populated by the Rust core: * {{{node.id}}} : Optimized incremental ID (e.g., 1, 2, 10). * {{{node.path}}} : Relative path. * {{{node.type_char}}} : [D] or [F] . * {{{node.mod}}} : Unix timestamp in milliseconds. Available to custom templates. The built-in default template does not print it since 1.0.1, because a timestamp changes on a bare touch and breaks the byte-stable prefix of the page; --tree-stamps=on selects the built-in stamped template (the 1.0.0 text, MOD: and SIZE: on every tree line, MOD in the instructions). The default entry also leaves out {{{node.size_part}}} , since a size changes on every ordinary edit; {{{node.size}}} and {{{node.size_part}}} stay available to custom templates. * {{{node.size}}} : File size in bytes. * {{{file.lines}}} : Line count of the file. * {{{file.content}}} : Actual file content. --- url: https://www.dctx.internet.technology/playground/ title: Playground source: https://www.dctx.internet.technology/playground/ --- Playground Playground Run the real dctx 1.3.1 on a bundled sample or on text files you paste. Each run gets a fresh directory and an empty environment, and is limited to 3 s, 2 s of CPU and 256 MiB; nothing is stored. Commands are checked against the CLI's own options and never reach a shell. Command (after dctx ) map find greet map find greet --json map neighbors 's:src/util.rs#greet' --edge calls --dir in map read 's:src/util.rs#greet' --json map skeleton src/store.rs map hubs --limit 10 map path 's:src/main.rs#main' 's:src/store.rs#save' map export --format mermaid pack . --for 'greet store' --budget 600 pack . --ext rs languages Place A sample My files Sample kiosk: the sample of every example on the website (Rust, TypeScript, Python, TOML, Markdown) Go lexer fixtures (crates/dctx-lex-go/tests/fixtures) Parser test fixtures in 15 formats: C, C#, Go, Java, JavaScript, Kotlin, Markdown, PHP, Python, Ruby, Rust, Swift, TOML, TypeScript, YAML (crates/dctx-map-parse/tests/fixtures) My files: each starts with a line --- path --- ; text only, at most 48 files, 96 KiB each --- src/lib.rs --- /// Adds two numbers. pub fn add(a: i32, b: i32) -> i32 { a + b } pub fn twice(x: i32) -> i32 { add(x, x) } --- app/main.py --- from lib import twice def run(): return twice(21) Run API (OpenAPI) Without JavaScript the form opens the result as a page. The playground service is not reachable. Everything else on this site works, and the runs below were recorded from dctx 1.3.1 when the site was built. dctx # results appear here API GET /api/v1/health Version, sample count and limits GET /api/v1/samples The bundled sample projects POST /api/v1/run Run one dctx command POST /api/v1/run-form The same as /run for an HTML form, answered with an HTML page GET /api/v1/metrics.json Counters: runs, cache hits, timeouts, refusals by reason, median run time GET /api/v1/openapi.json This document Recorded runs Captured at build time on the kiosk sample; the playground returns the same bytes for the same command. dctx map find greet recorded on kiosk $ dctx map find greet # kiosk find s:src/util.rs#greet fn L2-4 s:web/app.ts#renderGreeting fn L10-12 # exit 0 · 79 bytes · ~23 est. tokens dctx map neighbors s:src/util.rs#greet --edge calls --dir in recorded on kiosk $ dctx map neighbors 's:src/util.rs#greet' --edge calls --dir in # kiosk neighbors calls:in: s:src/main.rs#main fn src/main.rs L7 # exit 0 · 64 bytes · ~19 est. tokens dctx map skeleton src/store.rs recorded on kiosk $ dctx map skeleton src/store.rs # kiosk skeleton m:src/store.rs module L1-24 src/store.rs s:src/store.rs#Order struct L4-8 pub struct Order s:src/store.rs#save fn L11-14 pub fn save (order: & Order ) s:src/store.rs#encode fn L17-19 fn encode (order: & Order ) s:src/store.rs#checksum fn L22-24 fn checksum (text: & str ) # exit 0 · 280 bytes · ~80 est. tokens dctx map path s:src/main.rs#main s:src/store.rs#save recorded on kiosk $ dctx map path 's:src/main.rs#main' 's:src/store.rs#save' # kiosk path start s:src/main.rs#main fn src/main.rs calls:out s:src/store.rs#save fn src/store.rs # exit 0 · 99 bytes · ~29 est. tokens --- url: https://www.dctx.internet.technology/benchmarks/ title: Benchmarks source: https://www.dctx.internet.technology/benchmarks/ --- Evidence Benchmarks Compare dctx with grep plus file reads, then measure the whole agent session. Startup instructions, tool definitions and extra turns can outweigh smaller answers. Grep plus file reads Measured whole-session results, 11 November 2026. Full report and method Measured on 11.11.2026. NOT STABLE : dctx remains an advanced tool. On this corpus and model dctx did not save 25 % tokens. The pre-registered success rule was not met : CLI median total tokens were -5.01 % versus grep. The claim supported here is accuracy and bounded context , not token savings. Method # Corpus: a private 13-crate Rust workspace; it is not public. Questions: 20, covering code location, call sites and multi-hop traces. Model: claude-sonnet-5-5 via Claude CLI. dctx: 1.3.0 ( 156e1bb ), not current HEAD. Three repeats per arm. Only tool exposure differs; prompt, model and question order are identical. Blind grading uses opaque ids without arm labels. Arm Tools and cache conditions A Read + Grep/Glob: grep plus file reads baseline B Read + Bash restricted to dctx * ; index warm before measurement These are whole-session measurements, including conversation replay and provider cache usage, rather than estimates of tool stdout. The warm index in B excludes its preparation cost; these results do not measure cold indexing. Cost and turns # Totals per arm cover all 20 questions; each cell is the median [min, max] of three runs. Total tokens = uncached input (including cache creation) + cached input + output. Each metric is summarized independently, so component medians need not sum to the median total. Turns are CLI num_turns , an assistant-turn proxy, not exact tool calls. Metric A: grep plus reads B: dctx CLI Total tokens 14,904,014 [14,604,149, 15,622,381] 14,157,974 [11,221,908, 15,613,375] Uncached input tokens 286,289 [284,340, 290,043] 250,479 [220,537, 258,313] Cached input tokens 14,543,028 [14,241,089, 15,246,829] 13,833,705 [10,939,641, 15,278,757] Output tokens 78,720 [74,697, 85,509] 73,790 [61,730, 76,305] Wall time (s) 700.87 [697.78, 811.59] 719.84 [628.75, 768.06] Turns ( num_turns ) 172 [159, 175] 130 [129, 137] B versus A median total tokens: -5.01 % . Accuracy: both metrics # The official metric is strict citation recall: exact repo-relative path and line, with a tolerance of +/-3 lines, against 574 required line references per run. The diagnostic metric is file-level recall: the required file named in full anywhere in the answer, against 106 file/question pairs per run. Metric A: grep plus reads B: dctx CLI Official strict citation recall, median [min, max] 10.10 % [10.10, 20.73] 14.46 % [8.36, 22.65] Diagnostic file-level recall, median 53.77 % 71.70 % A grader audit found no grader defect. Low strict recall comes from answers citing shorthand paths such as store.rs:313 , and from line-level granularity: 10 trace questions hold 82 % of required lines. File-level recall is a diagnostic, not a replacement metric. No file-level spread is supplied. Where savings would come from # dctx on its own does not save tokens by default. Token savings come from systems that use dctx: a harness or agent system built around its cache-hit philosophy, reusing byte-identical, prefix-stable context across long sessions over a large body of work. In that setting it behaves like any sufficiently advanced caching mechanism, with one difference: you have complete control over every byte of the context. The system must arrange that reuse; merely exposing dctx tools does not do it. There is no measured, citable savings figure for such a system yet. See the philosophy . Verdict and limitations # The pre-registered rule required B to save at least 25 % median total tokens and match or exceed A's recall. NOT MET on tokens (-5.01 %) , even though B's median official recall exceeded A's. On this corpus and model dctx did not save 25 % tokens. B named more of the required files than grep at about equal token cost. This supports an accuracy and bounded context claim, not a whole-session token-savings claim. The bounded context behavior is described in Choosing how to use dctx ; these results do not establish a general accuracy advantage. Limitations: one corpus, one model, three repeats, and no significance claim. The corpus and raw answers are private and cannot be published; these aggregate results cannot be independently reproduced from the public repository alone. dctx 1.3.0 is not current HEAD. The guidance Under ~200 files, use grep stays. The earlier measurement evidence preserves the historical tool-output protocols separately from this whole-session study. Secondary historical evidence All other-tool tables below preserve the October research record. Their tokens are tool stdout estimates, not whole-session cost; scores measure gold facts in raw output without an agent model. The dctx team designed the 70-question protocol. The independent run selected repositories by seed and used language-server gold. Historical run 7: task-level protocol 70 questions, 354 gold facts, 31 October 2026. BENCHMARK-20261030.md Tool Points /140 Gold facts /354 Tokens Facts per 1k tokens dctx 53f8b6b 140 (run 6: 136) 353 (342) 29,340 12.0 Trail-Code 0.28.0 122 312 88,923 3.51 graphify 0.9.97, code-only 96 238 197,203 1.21 By question type Points out of 14 per type, from run 5 and task re-run 3 (dctx a906884 ), the last run with a per-type table; run 7 then scored every point on all ten types. run 7 note BENCHMARK-20261030.md Type dctx Trail-Code graphify definition and callers 14 10 10 impact 14 13 12 outline 14 14 12 config key 14 14 6 exports 14 14 14 source 14 12 0 callees 10 8 8 overview 14 13 11 collision 14 12 13 concept 14 12 10 Independent benchmark, 31 October 2026 Seeded selection of 3 repos the tools never saw (zoxide, requests, gin), gold from language servers and repo history, published regardless of outcome. Tasks: dctx 22/28 points, 31/36 facts, 6.85 facts per 1k tokens (Trail-Code 19/28, graphify 14/28). Callers against LSP gold, first page: dctx P 0.730 / R 0.341, Trail-Code P 0.731 / R 0.313, graphify P 0.920 / R 0.264. Honest read: dctx leads on task answers and token efficiency; caller recall on unseen repos is far below the in-house corpus (0.851), so the caller floors above hold only for the curated corpora. Full table and raw JSON: docs/research/bench-independent/results/20261031T191225Z/ . BENCHMARK-20261030.md Cold index Run 7 medians of three runs: dctx 0.13–1.20 s on 6 corpora, Trail-Code 1.04–52.83 s, graphify 4.59–59.56 s (5 corpora; no index on docs). run7 aggregate.json corpus dctx Trail-Code graphify flask 0.13 s 3.82 s 8.02 s ripgrep 0.88 s 3.21 s 10.33 s pocketbase 0.93 s 50.54 s 59.56 s trailcode 1.20 s 52.83 s 45.55 s mixed 0.39 s 3.97 s 4.59 s docs 0.19 s 1.04 s no index Run 1 (30 October), with peak memory and index size: median wall s, peak RSS of the largest process, index size. BENCHMARK-20261030.md corpus dctx Trail-Code graphify flask (Python) 0.16 s, 19 MB, 1.1 MB 4.17 s, 225 MB, 4.4 MB 8.13 s, 102 MB, 4.5 MB ripgrep (Rust) 0.54 s, 25 MB, 2.2 MB 3.01 s, 303 MB, 8.4 MB 10.45 s, 93 MB, 8.6 MB pocketbase (Go+JS) 0.91 s, 63 MB, 9.9 MB 50.63 s, 987 MB, 41.8 MB 58.96 s, 243 MB, 26.3 MB trailcode (TS) 1.16 s, 90 MB, 14.8 MB 58.34 s, 1,020 MB, 41.1 MB 44.32 s, 394 MB, 11.9 MB mixed (10 langs) 0.24 s, 74 MB, 2.8 MB 3.84 s, 470 MB, 12.8 MB 4.46 s, 74 MB, 2.2 MB docs 0.18 s, 74 MB, 1.4 MB 1.17 s, 121 MB, 0.0 MB failed: no index Warm queries and answer size Run 1, median ms of 5 after one warm-up, including process start, and estimated tokens. BENCHMARK-20261030.md corpus query dctx Trail-Code graphify flask search 81 ms, 218 1,066 ms, 262 564 ms, 1,845 flask callers 47 ms, 479 988 ms, 136 381 ms, 32 flask skeleton 44 ms, 866 991 ms, 852 514 ms, 474 flask overview 45 ms, 491 1,009 ms, 1,122 7 ms, 5,930 pocketbase search 213 ms, 259 1,573 ms, 358 1,393 ms, 97 (exit 3) pocketbase callers 214 ms, 464 1,195 ms, 175 777 ms, 24 pocketbase overview 226 ms, 652 1,232 ms, 1,514 8 ms, 11,591 trailcode callers 200 ms, 472 1,180 ms, 1,064 715 ms, 196 trailcode overview 195 ms, 500 1,159 ms, 499 7 ms, 10,076 Byte stability Build 0495f5f , 6 November 2026, three pinned corpora, 11 query shapes each. REPORT.md · full report Measurement Text JSON Answers identical after unrelated edit 33/33 33/33 Answers identical over five separate invocations 33/33 33/33 Baseline -> post-edit common-prefix ratio, minimum / mean 1.0 / 1.0 1.0 / 1.0 Consecutive same-request transitions, five per case 165 165 Same-request M7, minimum / mean 1.0 / 1.0 1.0 / 1.0 Consecutive changing-question transitions 195 195 Changing-question M7, minimum / median / mean 0.007795889 / 0.107142857 / 0.214830257 0.008776458 / 0.067594433 / 0.182446794 Changing-question M7, total prefix bytes / total current bytes 0.061846978 0.079892615 Not claimed These exclusions apply to the historical tool-output protocols below the whole-session summary above. Whole-session cost or task-level answer quality from these historical protocols. Historical fact scores describe raw tool outputs only; the 11 November study measures whole sessions with a frozen model. Anything about graphify's LLM semantic graph, or Trail-Code's learnings and LSP edges. SWE-bench scores or agent-run numbers from these historical tool-output protocols. Equal language depth. dctx's 25 new formats are outline tier: symbols, not call edges. Historical raw data The whole-session corpus and raw answers are private and cannot be published. The links below cover only the historical studies. docs/research/bench-3way-20261030/ : questions, gold facts, scorer, raw results and scripts The full write-up , with every run and the method The earlier two-way study (October 2026, before call edges) --- url: https://www.dctx.internet.technology/changelog/ title: Changelog source: https://github.com/Eris-Margeta/dctx/blob/main/CHANGELOG.md --- Changelog Changelog Every release, including known issues we have measured and not yet fixed. Generated from CHANGELOG.md ; also an Atom feed . --- url: https://www.dctx.internet.technology/news/ title: News source: https://www.dctx.internet.technology/news/ --- News News Releases, measurements and product decisions. Also an Atom feed . 4 November 2026 Release dctx 1.1: three more languages, a prefix-stable pack, and a measured lead. Perl, Fortran and Verilog join map mode; dctx pack drops timestamps so prompt caches hit; the three-way benchmark and the byte-stability measurement are public. 21 October 2026 Announcement dctx Desktop is now free. Forever. For individuals, teams and companies. No trial, no seat count, no expiry. 21 October 2026 Engineering Our specification, and a benchmark that does not flatter us. The dctx Context Management Specification, and an isolated comparison with Trail-Code: wins, losses and what comes next. --- url: https://www.dctx.internet.technology/news/dctx-1-1/ title: dctx 1.1: three more languages, a prefix-stable pack, and a measured lead. source: https://www.dctx.internet.technology/news/dctx-1-1/ --- Release dctx 1.1: three more languages, a prefix-stable pack, and a measured lead. Perl, Fortran and Verilog join map mode; dctx pack drops timestamps so prompt caches hit; the three-way benchmark and the byte-stability measurement are public. 4 November 2026 The dctx project dctx 1.3.1 was released on 4 November 2026. It folds in the 1.0.1 line and follows the first v1 release of 31 October. What is new Perl, Fortran and Verilog/SystemVerilog join the full tier, with symbols and lexical call edges labelled guess . dctx now covers 50 language families: 36 full, 8 outline and 6 documentation formats. A prefix-stable dctx pack . Tree lines carry the file id only, with no modification time and no size, so a bare touch leaves the page byte-identical and an edit keeps everything before the edited file as a shared prefix. --tree-stamps=on brings back the 1.0.0 lines. Faster id lookup , record and entry caps checked during the scan, and a closed stdout pipe that exits cleanly. Historical output-only measurements These other-tool results are retained as release history. Tokens here estimate tool stdout, not whole-session cost. The current baseline is grep plus file reads ; choose a mode and count startup context and all model turns. On our own 70-question protocol, run on 31 October against Trail-Code 0.28.0 and graphify 0.9.97 in code-only mode, dctx scored 140 of 140 points with 29,340 estimated tokens; Trail-Code scored 122 with 88,923 and graphify 96 with 197,203. Cold indexing of the six corpora took dctx 0.13–1.20 s. That protocol was designed by the dctx team and can favour dctx. An independently selected protocol is pending, and we will publish its result whatever it shows. On 6 November, 33 of 33 text answers and 33 of 33 JSON answers stayed byte-identical after unrelated edits across three pinned corpora. Three weeks earlier, answer headers that changed after unrelated edits were one of the findings that our first benchmark held against us. Benchmark write-up · Stability report · Full changelog All news --- url: https://www.dctx.internet.technology/news/desktop-free-forever/ title: dctx Desktop is now free. Forever. source: https://www.dctx.internet.technology/news/desktop-free-forever/ --- Announcement dctx Desktop is now free. Forever. For individuals, teams and companies. No trial, no seat count, no expiry. 21 October 2026 The dctx project Starting today, the dctx desktop app is free for everyone who uses it: a single developer, a ten-person studio or an engineering organisation of thousands. It stays that way. Why we are doing this dctx exists because of one belief: prompt-processing efficiency. Every token in front of a model is paid for three times, in prefill, in cache misses and in attention. dctx supplies bounded, byte-stable context; it does not save tokens by default. Savings belong to a harness or agent system that reuses byte-identical, prefix-stable context across long sessions over a large body of work, with control over every byte. No measured savings figure exists for such a system yet. The desktop app is how people who do not live in a terminal reach that engine: designers, analysts, product managers and engineers who simply prefer a window. Charging for it put a toll at the front door of the very habit we want to spread. So we are removing the toll. Efficient context should be the default for everyone who works with a model, not a premium feature. What you get The same engine as the command line and the library: one core, the same privacy guarantee, the same output. Drag-and-drop or native folder selection, and snapshots generated without blocking the interface. Your global dctx settings and ignore rules, applied exactly as on the command line. Everything runs on your machine. No account, no telemetry, no network. The source is in the open repository under Apache-2.0, next to the CLI and the core. The desktop app is a preview on its own version line (0.11), source only: there is no download yet, so build it from the repository. What does not change dctx remains open source. The repository is ongoing work, and we publish what we measure, including where we still have work to do, as in our first public benchmark . Organisations that depend on dctx can sign a maintenance agreement for security response times, long-term support and priority work. Paying never changes the license, and it funds the work that keeps the desktop app free. Already bought a license? Thank you. You helped build what everyone now gets for free. All news --- url: https://www.dctx.internet.technology/news/specification-and-benchmark/ title: Our specification, and a benchmark that does not flatter us. source: https://www.dctx.internet.technology/news/specification-and-benchmark/ --- Engineering Our specification, and a benchmark that does not flatter us. The dctx Context Management Specification, and an isolated comparison with Trail-Code: wins, losses and what comes next. 21 October 2026 The dctx project Historical post. These results describe dctx as of October 2026, before call edges and byte-stable answers. For current measurements, read dctx 1.1 . An engineering organisation should be able to check every claim a tool makes. So we wrote down exactly what dctx is meant to be, and then measured where it stands today. The specification The dctx Context Management Specification turns our core belief, prompt-processing efficiency, into five testable constraints: every answer is bounded, deterministic, prefix-stable, non-redundant and honest about its precision and freshness. It names ten ways chunk retrieval fails and the mechanism that rules out each one, defines a seven-layer organisation policy in which every layer can only narrow the one above it, and lays out the roadmap with an acceptance gate for every step. Each item is marked as available, under contract or a target. The benchmark This is a secondary historical comparison of tool outputs, not whole-session agent cost. The current baseline is grep plus file reads . We ran dctx and Trail-Code side by side on a dedicated machine: seven pinned code bases in Rust, Go, Python and TypeScript, no network during the runs, every command pinned to the same CPUs, and an adversarial corpus with planted secrets. The full report, raw data and scripts are public so anyone can rerun it. Where dctx led Cold indexing on every code base: 0.09–6.05 s against 2.4–95 s, with 1.6–27× less memory. Footprint: one 9.2 MB binary against 405.6 MB of Node.js packages. Bounds: map answers never exceeded their token budget. Network: dctx opened no sockets and wrote nothing into the repositories. Where Trail-Code led Call graphs: dctx's map command did not yet expose call or import edges. Answers to agent questions: 122 of 140 points against 69 of 140, with fewer tokens. Stability under edits: Trail-Code kept most answers byte-identical after an unrelated change; dctx did not, which costs prompt-cache hits. Incremental refresh after an edit. What happens next The findings are now the first items on our roadmap: call and import edges with honest confidence labels, a persistent incremental index, answer headers that stay stable across unrelated edits, a bounded repository overview, a search verb, and safer defaults for secrets when packing a whole project. Each one ships only when it passes the gate the specification sets for it, and we will publish the next measurement the same way. Read the specification · Read the benchmark report All news --- url: https://www.dctx.internet.technology/security/ title: Security policy source: https://github.com/Eris-Margeta/dctx/blob/main/SECURITY.md --- Document: `SECURITY.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/security/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt Security Policy View source · Edit on GitHub · Markdown · SECURITY.md · 561 words · updated 7 November 2026 On this page Supported versions Reporting a vulnerability What counts as a vulnerability Handling and disclosure Supported versions # for six months after the new major's release date , then reaches end of support. Reporting a vulnerability # Do not disclose vulnerabilities in public issues or pull requests. Use or email info@tejl.com with a subject beginning [dctx security] . If GitHub's private reporting form is unavailable, use email. What counts as a vulnerability # Handling and disclosure # We acknowledge private vulnerability reports within 7 days . We investigate README and plugin guide . --- url: https://www.dctx.internet.technology/trademark/ title: Trademark policy source: https://github.com/Eris-Margeta/dctx/blob/main/TRADEMARK.md --- Document: `TRADEMARK.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/trademark/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt dctx trademark policy View source · Edit on GitHub · Markdown · TRADEMARK.md · 148 words · updated 7 November 2026 On this page Forks and redistribution What needs permission What is always fine Forks and redistribution # What needs permission # What is always fine # --- url: https://www.dctx.internet.technology/maintenance/ title: Maintenance source: https://github.com/Eris-Margeta/dctx/blob/main/MAINTENANCE.md --- Document: `MAINTENANCE.md` in [Documents](#documents). [Read the page](https://www.dctx.internet.technology/maintenance/). Rendered text and page details not already verbatim in the document pack: All documents Start What dctx is Choose your path Safe path in ten minutes Why dctx README and quick start Modalities Choosing how to use dctx CLI and agents: map mode Agent snippet Libraries CI and caching Plugins guide Scopes Two scopes, one binary Who is responsible for what Engine Specification Privacy guarantees Cache and limits Language coverage (ADR-018) Template contract (DTS v2) Templating engine (ADR-003) Crate map Reference CLI reference CLI exit codes Languages Templates Examples Trust Benchmarks Measurement evidence Byte-stability report Earlier two-way study Philosophy Security policy Releasing Contributing Trademark Maintenance For AI evaluators Facts and verification llms.txt dctx maintenance View source · Edit on GitHub · Markdown · MAINTENANCE.md · 332 words · updated 7 November 2026 On this page What an agreement covers Tiers Pricing and contact Guarantees What an agreement covers # Security fixes. Response targets are counted from the moment a report is confirmed: Long-term support. The 1.x line receives backported fixes for 18 months after 2.0 is released. Priority on bug reports. Reports from covered organisations are triaged first. A say in the roadmap. Covered organisations can propose priorities in a regular review. The maintainer keeps the final decision. Advance notice of breaking changes. You hear about a breaking change before it ships, with a migration note. Invoice and written commitment. You receive invoices and a signed maintenance commitment for procurement and vendor review. Security reports still go through SECURITY.md , whatever your tier. Tiers # Supporter sponsorship runs through GitHub Sponsors . Team and Partner agreements are arranged directly. Pricing and contact # Guarantees # The core ( pack ) and every modality stay open. --- url: https://www.dctx.internet.technology/how-it-works/ title: How dctx works source: https://www.dctx.internet.technology/how-it-works/ --- Docs How dctx works Five short animations. Each has a caption with its one point and a text version underneath it when motion is off. Use the Motion toggle in the header to switch between them. Planned features are marked planned. Two scopes, one binary Cost is calls times context Edit a file, keep the cache The giant folder The safe path Two scopes, one binary The same engine can live in two places on one machine. Knowing which one you are calling avoids most version confusion. Pause animation: two scopes, one binary Replay animation: two scopes, one binary Same engine, different owner. The system dctx is yours; a project's dctx is pinned by that project. dctx doctor lists every dctx in reach; release archives are cosign-signed. What the animation shows, step by step: One machine. The system dctx on PATH (version 1.3.1) belongs to you and your agents; you decide when to upgrade it. A project vendors its own dctx inside node_modules or a virtualenv, pinned by its lockfile and upgraded only when the project bumps it. The Node wrapper is on npm as @tejl/dctx from 1.3.1; the pip package is built in CI, with registry publication pending. Both are the same engine at different versions. Interactive agents call the system binary; application code and CI call the project binary. A library never falls back to PATH silently. dctx doctor lists every dctx visible from the current folder with its version, build commit, scope and SHA-256. Verify prebuilt archives against SHA256SUMS and their cosign signatures. Cost is calls times context Whole-session cost depends on how many times the model reads the conversation, not only on how big one answer is. Pause animation: cost is calls times context Replay animation: cost is calls times context Calls cost more than output size. An illustration, not a measured result: every call re-reads the whole conversation so far. What the illustration shows (made-up units, not a benchmark): Each model call reads the whole conversation: the task and prompt, plus every earlier tool result. Agent A uses grep and file reads: eight calls with small results. The conversation grows a little with each call, and each call reads all of it again. Agent B uses dctx: two calls that return larger, bounded pages, then it is done. Adding up what every call re-reads (the shaded areas): 164 units for agent A, 29 for agent B. So the number of calls matters more than the size of one result. The reverse also holds: dctx used without a plan can add calls instead of removing them, so count the calls of your own sessions. Choosing how to use dctx explains how to count them. Edit a file, keep the cache Prompt caches reuse bytes up to the first change. A stable order without timestamps keeps that prefix long. Pause animation: edit a file, keep the cache Replay animation: edit a file, keep the cache Edit a file, keep the cache. Illustrative sizes. The pack keeps a stable order and carries no timestamps by default, so a prompt cache can reuse every byte before the edit. What the animation shows: Turn 1: the pack is sent as one strip of bytes, file after file in a fixed order; the model provider caches it. You edit one file near the end of that order. Turn 2: the same tree gives the same bytes up to that file, so only the edited file and what follows are new. The cache reuses the unchanged prefix, here about three quarters of the bytes. If the pack began with a timestamp, the first byte would change and nothing would be reused. dctx answers carry no timestamps, digests or ages by default; --meta adds them back. Ordering rarely changed files first (prefix tiers) is planned. The giant folder For a very large folder, the plan is to catalog names once and index only the parts a task needs. Pause animation: the giant folder Replay animation: the giant folder Index what the task touches, never copy the tree. The catalog and shards are the planned architecture. Today, point dctx at a sub-folder named in the task, not at the whole tree. What the animation shows (the planned architecture): A 200 GB folder: photos, datasets, archives and a folder of repositories. A catalog (planned) sweeps it once and records names and sizes only; no file contents are read. A task arrives: fix invoice rounding. Two shards match the task: repos/billing and repos/shared-ui . Only those two get symbol indexes; the rest of the tree is never indexed or copied. A bounded page, inside the budget and in a stable order, comes out of the two shards. What works today: start dctx on the sub-folder the task names (for example dctx map find invoice --place repos/billing ), with ignore rules for the rest. The safe path The shortest way to find out whether dctx helps your work, without changing several things at once. Pause animation: the safe path Replay animation: the safe path Measure before you change anything. The safe path for a new user, with commands that exist in dctx 1.3.1. Receipts are planned. If you are new, follow the safe path: one project, the system binary, direct CLI commands. Measure before you change anything. Step by step: A new user with one agent and one repository. Install the system binary: download the archive for your platform from GitHub Releases, check it with sha256sum -c SHA256SUMS --ignore-missing , then run dctx --version . Pick one project, not your home folder or a huge tree. The system binary serves it; nothing is installed per project. Run dctx map find NAME from the project root, then read a result with dctx read ID , using the shell or an agent's shell tool. Make the first call, for example dctx pack . --for 'greet store' --budget 800 , and read its last line: # end body_tokens=223 budget=800 dropped=0 on the sample project. Measure: per task, count the calls, the start-up tokens and the total input, and compare with grep and file reads on the same task. Receipts that count this for you are planned. Only then change one thing at a time. Next: Choosing how to use dctx · Examples · Benchmarks --- url: https://www.dctx.internet.technology/search/ title: Search source: https://www.dctx.internet.technology/search/ --- Search Search Titles, headings and text of every page, searched in your browser. Nothing is sent anywhere. Search the site Search needs JavaScript. Every page of the site: dctx / dctx is the open-source context engine for AI-assisted development: deterministic, bounded code context for agents and chat, offline, with no telemetry. Apache-2.0. Documentation /docs/ Specification, guides, benchmark reports and project policies for dctx, rendered from the repository. Choose your path /start/ dctx is an advanced tool with several ways to use it. Pick the path that matches your work: one giant folder, many small projects, a library in your own tool, or a team rollout. One giant folder /start/giant-folder/ You work inside one very large tree, for example a 200 GB monorepo, data or document folder. Setup, first command, what to expect and the pitfall to avoid. Many smaller projects /start/many-projects/ You move between many small and medium repositories during the day. Setup, first command, what to expect and the pitfall to avoid. Agent builder embedding a library /start/library/ You build an agent, editor or tool and want dctx inside it. Setup, first command, what to expect and the pitfall to avoid. Team or organisation admin /start/team/ You roll dctx out to a team or a fleet of machines. Setup, first command, what to expect and the pitfall to avoid. For AI evaluators /for-ai-evaluators/ What dctx is and is not, its version, modalities, benchmark status, removed commands and how to verify every claim. Why dctx /why/ Why dctx exists, its philosophy, and why byte-identical output keeps the prompt cache hitting. README /docs/readme/ Installation, quick start, map mode, language tiers and the CLI reference. What dctx is /docs/start/ The claim and its limits, the advanced-user notice, choose your path, the safe path in ten minutes, responsibilities and the two scopes. Choosing how to use dctx /docs/modalities/ Clipboard, grep plus reads, long sessions, huge trees, CLI usage and CI. Map mode guide /docs/map-mode/ Every map verb with examples, budgets, ids and precision labels. Agent snippet /docs/agents/ The AGENTS.md section that tells coding agents to ask dctx first. Plugins guide /docs/plugins/ The plugin boundary, capabilities, consent and current limits. Specification /docs/spec/ The core belief, the five constraints, the ten RAG defect classes, policy and roadmap. Privacy guarantees /docs/privacy/ Ignore semantics and the full sensitive-file deny list. Language coverage (ADR-018) /docs/language-coverage/ The three tiers and how a language enters one. Template contract (DTS v2) /docs/templates-contract/ DTS source v2 and the compiled plan IR v1. Templating engine (ADR-003) /docs/templating/ Markers, ahead-of-time compilation, the two rendering passes and the data variables. Crate map /docs/crate-map/ How the Rust workspace is organised. CLI exit codes /docs/exit-codes/ The exit-code contract for map, pack and languages. Measurement evidence /docs/benchmark/ Grep plus file reads first; whole-session scope and secondary historical protocols. Byte-stability report /docs/stability/ Protocol, raw answers and limits of the 33/33 measurement. Earlier two-way study /docs/benchmark-oct/ October 2026, before call edges: the benchmark that set the roadmap. Releasing /docs/releasing/ How a release is cut and checked. Contributing /docs/contributing/ How to propose changes, with a DCO sign-off. CLI reference /cli/ Every dctx command, flag, environment variable, and exit code, captured from the dctx binary. Languages /languages/ The 50 language families dctx indexes, by tier: full, outline and docs. Examples /examples/ Every dctx command on one sample project, with its exact output, exit code, bytes and estimated tokens. Templates /templates/ The two built-in dctx templates, their source, their output on the same project and what changes between them. Playground /playground/ Run the real dctx binary on a sample project or on your own text files, in the browser. Benchmarks /benchmarks/ Grep plus file reads, whole-session accounting, byte stability and secondary historical measurements. Changelog /changelog/ Every dctx release, from dircontxt 1.0.0 in C to dctx in Rust, with known issues. News /news/ Releases, measurements and product decisions from the dctx project. dctx 1.1: three more languages, a prefix-stable pack, and a measured lead. /news/dctx-1-1/ Perl, Fortran and Verilog join map mode; dctx pack drops timestamps so prompt caches hit; the three-way benchmark and the byte-stability measurement are public. dctx Desktop is now free. Forever. /news/desktop-free-forever/ For individuals, teams and companies. No trial, no seat count, no expiry. Our specification, and a benchmark that does not flatter us. /news/specification-and-benchmark/ The dctx Context Management Specification, and an isolated comparison with Trail-Code: wins, losses and what comes next. Security policy /security/ How to report a vulnerability privately, and what happens next. Trademark policy /trademark/ What the dctx name and logo may be used for, and what forks may call themselves. Maintenance /maintenance/ dctx is free under Apache-2.0. Maintenance agreements fund security response, long-term support and priority work. How dctx works /how-it-works/ Five short animations: two scopes of one binary, calls times context, prefix stability, the giant folder and the safe path for new users. --- url: https://www.dctx.internet.technology/playground/offline/ title: Playground offline source: https://www.dctx.internet.technology/playground/offline/ --- 503 The playground is offline. The service that runs dctx is not reachable right now; the rest of the site works. The examples were recorded from dctx 1.3.1 when this site was built. Recorded examples Playground --- url: https://www.dctx.internet.technology/404.html title: Page not found source: https://www.dctx.internet.technology/404.html --- 404 Page not found. There is no page at this address. It may have moved. Search the site Home Documentation CLI reference Examples ## CLI reference and examples (captured from the binary) --- url: https://www.dctx.internet.technology/cli/ title: CLI reference (captured help) source: https://github.com/Eris-Margeta/dctx/blob/main/tools/website/data/demo.json --- ```text $ dctx --help Usage: dctx <COMMAND> [OPTIONS] dctx pack [PATH] [--output PATH] [--clipboard] [--json] dctx pack [PATH] --for <TEXT> [--budget TOKENS] dctx map <map|find|neighbors|explain|read|skeleton|grep|hubs|path|export> [--json] dctx context TARGET [--place PATH] [--budget N] [--json] [--session ID --dedupe] dctx rpc dctx trace <A> <B> [--max-depth N] [--max-paths N] [--max-bytes N] [--json] dctx impact <SYMBOL> [--max-depth N] [--max-sites N] [--max-bytes N] [--json] dctx read <TARGET> [OPTIONS] dctx languages [--json|--markdown] dctx doctor [--json] dctx agent-setup [--format claude|agents|plain] dctx cache status [--json] [--root PATH] dctx cache gc [--dry-run] [--root PATH] [--max-bytes N] dctx cache purge --root PATH [--dry-run] [--yes] dctx cache purge --all [--dry-run] [--yes] dctx cache config [auto on|off] [--max-bytes N] [--ttl-days N] dctx cache auto [--json] dctx template build <PATH> [--output PATH] dctx template list [--dir PATH] dctx plugin search|install|list|info|enable|disable|remove|update|verify dctx git <status|protect> `dctx languages` lists every supported language with its tier: full (symbols and call edges), outline (symbols only) or docs (sections). `dctx rpc` serves the versioned engine protocol for language packages (send hello first; docs/protocol/README.md). `dctx read` uses `dctx map read`. Explicit `dctx pack` writes stdout, the clipboard, or `--output`. It does not create a project text file. `dctx pack --for <TEXT>` prints task context for an agent card instead: map find, neighbors and read of the names in TEXT, cut to `--budget` estimated tokens (default 3000). `dctx plugin list` and `dctx --help` do not create a project `.dctx/` directory or start a plugin. `dctx git` routes to the bundled dctx/git plugin. It is not a Git passthrough. Cache purge requires `--root PATH` or `--all`, and `--yes` unless `--dry-run` is set. `dctx cache config` shows the persisted policy. `auto on|off` enables auto-clean, `--max-bytes` tightens the system cap, and `--ttl-days` sets idle overlay and preview lifetime. `dctx cache auto` prints the last auto-clean time, the bytes it reclaimed and the next due time. `dctx doctor` lists visible binaries, ownership scopes, SHA-256 checksums and cache sizes without changing the cache or using the network. `dctx agent-setup` prints concise rules to paste into CLAUDE.md or AGENTS.md (default: agents). pack, map, template, plugin and the TUI run one bounded auto-clean when it is due. They print nothing unless bytes were reclaimed. `--no-auto-clean` and `DCTX_AUTO_CLEAN=0` disable that slice. `DCTX_CACHE_DIR` selects the cache parent; indexes live in its engine-major.minor subdirectory. General Options: -h, --help Show help -v, --version Show version --verbose With --version, also show executable path, scope and limits Run `dctx pack --help` for pack options and filters. Template Commands: template build <PATH> Compile a template through the facade template list List explicit compiled plans; no home-directory scan Examples: dctx pack . Pack to stdout and write no project text file dctx pack . --output out.txt dctx languages --json dctx cache status --json dctx cache gc --dry-run dctx cache purge --root /path --dry-run dctx cache config auto off --max-bytes 1000000 --ttl-days 7 dctx cache auto dctx template build policy.dctx_template Feature and precision limits: facade_version: 1.3.1 profile: enhanced wire_version: 2 segment_version: 1 storage: buffered-segments features: pack,map,templates,fs,segments,cache,syntax-rust parsers: dctx-structural/3,dctx-lex-js:1,dctx-lex-md:1,dctx-lex-rust/syn-3.0.9 languages: rust,javascript,typescript,python,go,java,c,csharp,kotlin,ruby,php,swift,web,scala,dart,zig,solidity,gleam,fortran,perl,groovy,powershell,elixir,lua,ocaml,r,julia,haskell,erlang,verilog,hcl,sql,clojure,lisp,scheme,elisp,config,shell,make,docker,proto,pascal,graphql,nix,markdown,text,rst,asciidoc,org,tex unsafe_boundary: syn-dependency native_code: false git: false subprocess: none precision: the structural extractor reports declarations, imports, headings and conservative calls. It does not promise exact semantic calls, name or type resolution, or macro expansion. A syntax-rust build adds syn for supported Rust syntax only, still without type checking. token estimate: ceil(2 * UTF-8 bytes / 7) is an estimate, not a tokenizer guarantee. cache cap: 2 GiB hard, 1.5 GiB soft watermark, 1.2 GiB eviction target. cache ttl: idle overlays and previews 7 days, unpinned roots 30 days, staging 1 day. auto-clean interval: 1 day. $ dctx map --help Usage: dctx map <map|find|neighbors|explain|read|skeleton|grep> <TARGET> [OPTIONS] dctx trace <A> <B> [--max-depth 1..16] [--max-paths 1..100] [--max-bytes 256..1048576] [--json] dctx impact <SYMBOL> [--max-depth 1..16] [--max-sites 1..10000] [--max-bytes 256..1048576] [--json] dctx map hubs [--limit N] [--json] [--place PATH] [--budget TOKENS] [--meta] Most-called symbols (incoming calls and imports, 1..60 lines, default 20) and per-directory file and symbol counts. No TARGET. dctx map path <FROM> <TO> [--json] [--place PATH] [--budget TOKENS] [--meta] Shortest edge path (calls, imports, contains; either direction; at most 8 hops), one `edge:out|in<TAB>id<TAB>kind<TAB>path` line per hop, or `no path`. dctx map export [--format json|mermaid] [--output PATH] [--place PATH] The whole graph as one deterministic document (default json: nodes and edges; mermaid: a flowchart of calls and imports). No TARGET, no token cap; --output writes a file. TARGET Required. map accepts a stable id or a place-relative file. skeleton takes a file (or m:<path>) and prints its declaration signatures, no bodies, in source order: id, kind, L<start>-<end>, signature. A file path is read as m:<path>. Omitting TARGET does not scan. --json Facade JSON v2, including the precision label --also DIR Add a read-only root (repeatable); paths and ids carry directory labels --place PATH Place or worktree root (default: current directory) --meta Restore the snapshot digest and generation in the text header and the snapshot, generation and age_s JSON fields. Without it the answer bytes do not change across unrelated edits or time. --profile Stderr stage timings and the five slowest files. DCTX_PROFILE=1 is the same switch. DCTX_MAX_SOURCE_BYTES Env: total source bytes one scan may read, 1..17179869184 (default 1073741824 = 1 GiB). DCTX_MAX_RECORDS Env: files, symbols and edges one index may hold, 1..100000000 (default 1000000). A bigger place is refused while it is scanned. DCTX_MAX_ENTRIES Env: files and directories one scan may visit, 1..100000000 (default 100000). DCTX_FRESHNESS Env: strict_live hashes every file on a warm start; the default (stamp) trusts a file whose size, mtime and inode are unchanged and older than 2 s. --budget TOKENS Output tokens, 1..2000 (explain max: 1000). Read with no --budget uses the 2,000-token hard cap. --depth N Map: 1..3; neighbors: 1..4. Explain and read take no depth. --limit N Map, find and neighbors page size. Explain and read accept only 1. --offset N Refused. Pass the previous page's next value to --cursor. --cursor TOKEN Opaque continuation. A stale token is rejected. --kind fn,type,doc Find kinds --in PATH Find or grep within a relative path grep LITERAL Exhaustive literal search of indexed files, hits grouped by enclosing symbol -i, --ignore-case Grep: ASCII case-insensitive match --edge calls,imports Neighbor edge filter --dir in|out|both Neighbor direction --lines A-B --full Read those absolute source lines inside the node; full permits 400 --rev SHA Refused: this build does not link git Precision: structural declarations, imports, headings and conservative calls. Not exact semantic calls, type resolution or macro expansion. Token estimate ceil(2 * UTF-8 bytes / 7) is not a tokenizer guarantee. Example: dctx map find 'ignore rules' --json Example: dctx map map crates/dctx-cli/src/main.rs --depth 2 Example: dctx map map m:crates/dctx-cli/src/main.rs --cursor '<next from the previous page>' Each verb's own page and example: dctx map <verb> --help Exit codes: 0 ok, 1 no result (an id not in the index, a binary file), 2 usage, 3 index error; see docs/CLI-EXIT-CODES.md. $ dctx map map --help Usage: dctx map map <TARGET> [--depth 1..3] [--limit N] [--cursor TOKEN] [--json] [--place PATH] [--also DIR ...] [--meta] Outline of a file (m:<path> or a place-relative path) or a symbol and what it contains. Example: dctx map map src/lib.rs --depth 2 Every option and its bounds: dctx map --help $ dctx map find --help Usage: dctx map find <QUERY> [--kind fn,type,doc] [--in PATH] [--limit 1..40] [--cursor TOKEN] [--json] [--place PATH] [--also DIR ...] [--meta] Ranked symbols, modules, headings and config keys whose name or summary matches QUERY. Example: dctx map find 'ignore rules' --json Every option and its bounds: dctx map --help $ dctx map neighbors --help Usage: dctx map neighbors <TARGET> [--dir in|out|both] [--edge calls,imports] [--depth 1..4] [--limit N] [--json] [--place PATH] [--also DIR ...] [--meta] Edges of one node: callers with --dir in --edge calls, callees with --dir out. Example: dctx map neighbors 's:src/lib.rs#run' --dir in --edge calls Every option and its bounds: dctx map --help $ dctx map explain --help Usage: dctx map explain <TARGET> [--budget 1..1000] [--json] [--place PATH] [--also DIR ...] [--meta] One node with its signature and summary, no body. Example: dctx map explain 's:src/lib.rs#run' Every option and its bounds: dctx map --help $ dctx map read --help Usage: dctx map read <TARGET> [--lines A-B] [--full] [--budget TOKENS] [--cursor TOKEN] [--json] [--place PATH] [--also DIR ...] [--meta] The verified source text of one node; a long node pages with --cursor. Example: dctx map read 's:src/lib.rs#run' --lines 10-40 Every option and its bounds: dctx map --help $ dctx map skeleton --help Usage: dctx map skeleton <FILE> [--budget TOKENS] [--json] [--place PATH] [--also DIR ...] [--meta] Declaration signatures of one file in source order, no bodies. Example: dctx map skeleton src/lib.rs Every option and its bounds: dctx map --help $ dctx map grep --help Usage: dctx map grep <LITERAL> [-i] [--in PATH] [--limit N] [--json] [--place PATH] [--also DIR ...] [--meta] Exhaustive literal search of indexed files, hits grouped by enclosing symbol. Example: dctx map grep TODO --in src Every option and its bounds: dctx map --help $ dctx map hubs --help Usage: dctx map hubs [--limit 1..60] [--budget TOKENS] [--json] [--place PATH] [--also DIR ...] [--meta] Most-called symbols and per-directory file and symbol counts. No TARGET. Example: dctx map hubs --limit 10 Every option and its bounds: dctx map --help $ dctx map path --help Usage: dctx map path <FROM> <TO> [--budget TOKENS] [--json] [--place PATH] [--also DIR ...] [--meta] Shortest edge path (calls, imports, contains; at most 8 hops) between two nodes, or `no path`. Example: dctx map path 's:src/main.rs#main' 's:src/lib.rs#run' Every option and its bounds: dctx map --help $ dctx map export --help Usage: dctx map export [--format json|mermaid] [--output PATH] [--place PATH] [--also DIR ...] The whole graph as one deterministic document. No TARGET, no token cap. Example: dctx map export --format mermaid --output graph.mmd Every option and its bounds: dctx map --help $ dctx languages --help Usage: dctx languages [--json | --markdown] Lists every language the map index recognises: name, tag, file names, tier and symbol confidence. Tiers: full = symbols and call edges (lexical, not type-resolved); outline = symbols only, no call edges promised; docs = headed sections. Confidence `guess` marks heuristic outlines, whose records carry confidence `guess`. Options: --json One JSON document with the tiers and the languages --markdown The README language table -h, --help Show this help Example: dctx languages --json ``` --- url: https://www.dctx.internet.technology/examples/ title: Examples (captured on the kiosk sample) source: https://github.com/Eris-Margeta/dctx/blob/main/tools/website/data/demo.json --- ### dctx --version exit 0, 23 bytes, ~7 est. tokens ```text dctx 1.3.1 (<git sha>) ``` ### dctx pack . exit 0, 5545 bytes, ~1585 est. tokens ```text [DCTX_LLM_CONTEXT_SNAPSHOT_V1] [DIRECTORY:kiosk] <INSTRUCTIONS> 1. Manifest: The <DIRECTORY_TREE> section lists all files. - Each entry: [TYPE] RELATIVE_PATH (ID:UNIQUE_ID) - TYPE is [D] for directory, [F] for file. 2. Content Access: To read a specific file: - Find its UNIQUE_ID from the directory tree. - Search for the marker: <FILE_CONTENT_START ID="UNIQUE_ID"> - The content is between this marker and </FILE_CONTENT_END ID="UNIQUE_ID"> </INSTRUCTIONS> <DIRECTORY_TREE> [D] (ID:ROOT) [F] .env (ID:F001) [F] .gitignore (ID:F002) [F] Cargo.toml (ID:F003) [F] README.md (ID:F004) [F] config.toml (ID:F005) [D] src (ID:D006) [F] src/main.rs (ID:F007) [F] src/store.rs (ID:F008) [F] src/util.rs (ID:F009) [D] tools (ID:D010) [F] tools/report.py (ID:F011) [D] web (ID:D012) [F] web/app.ts (ID:F013) [F] web/format.ts (ID:F014) </DIRECTORY_TREE> <FILE_CONTENT_START ID="F001" PATH=".env" LINES="0"> [Content omitted by pattern rules] </FILE_CONTENT_END ID="F001"> <FILE_CONTENT_START ID="F002" PATH=".gitignore" LINES="2"> target/ </FILE_CONTENT_END ID="F002"> <FILE_CONTENT_START ID="F003" PATH="Cargo.toml" LINES="9"> [package] name = "kiosk" version = "0.1.0" edition = "2021" description = "A tiny order kiosk: the sample project for the dctx website examples." license = "Apache-2.0" [dependencies] </FILE_CONTENT_END ID="F003"> <FILE_CONTENT_START ID="F004" PATH="README.md" LINES="19"> # kiosk A tiny order kiosk. It is the example project that every command on the dctx website runs on. ## Run cargo run -- ada prints `Hello, Ada!` and saves order 1 to `orders/1.tsv`. ## Orders Each order is one tab-separated line: id, item, quantity and a checksum of the item name. `python3 tools/report.py orders/` sums the quantities. ## Configuration `config.toml` holds the currency and the screen title. Secrets live in `.env`, which is never committed. </FILE_CONTENT_END ID="F004"> <FILE_CONTENT_START ID="F005" PATH="config.toml" LINES="7"> [screen] title = "kiosk example" currency = "EUR" [orders] folder = "orders" </FILE_CONTENT_END ID="F005"> <FILE_CONTENT_START ID="F007" PATH="src/main.rs" LINES="11"> //! kiosk: greet a customer, take one order, save it. mod store; mod util; fn main() { let name = std::env::args().nth(1).unwrap_or_else(|| "guest".to_string()); println!("{}", util::greet(&name)); let order = store::Order { id: 1, item: "coffee".to_string(), qty: 2 }; store::save(&order).expect("save order"); } </FILE_CONTENT_END ID="F007"> <FILE_CONTENT_START ID="F008" PATH="src/store.rs" LINES="25"> use std::io; /// One order as the kiosk records it. pub struct Order { pub id: u32, pub item: String, pub qty: u32, } /// Write the order to orders/<id>.tsv. pub fn save(order: &Order) -> io::Result<()> { std::fs::create_dir_all("orders")?; std::fs::write(format!("orders/{}.tsv", order.id), encode(order)) } /// One tab-separated line with a checksum of the item name. fn encode(order: &Order) -> String { format!("{}\t{}\t{}\t{:08x}\n", order.id, order.item, order.qty, checksum(&order.item)) } /// FNV-1a over the bytes of the text. fn checksum(text: &str) -> u32 { text.bytes().fold(0x811c9dc5, |hash, byte| (hash ^ u32::from(byte)).wrapping_mul(0x0100_0193)) } </FILE_CONTENT_END ID="F008"> <FILE_CONTENT_START ID="F009" PATH="src/util.rs" LINES="14"> /// The greeting shown on the kiosk screen. pub fn greet(name: &str) -> String { format!("Hello, {}!", title_case(name)) } /// Upper-case the first letter of a name, leave the rest as typed. pub fn title_case(name: &str) -> String { let mut chars = name.chars(); match chars.next() { Some(first) => first.to_uppercase().chain(chars).collect(), None => String::new(), } } </FILE_CONTENT_END ID="F009"> <FILE_CONTENT_START ID="F011" PATH="tools/report.py" LINES="19"> """Sum the quantities of every saved order: python3 tools/report.py orders/""" import sys from pathlib import Path def read_orders(folder): for path in sorted(Path(folder).glob("*.tsv")): order_id, item, qty, _checksum = path.read_text().rstrip("\n").split("\t") yield order_id, item, int(qty) def main(folder="orders"): total = sum(qty for _, _, qty in read_orders(folder)) print(f"{total} items") if __name__ == "__main__": main(*sys.argv[1:]) </FILE_CONTENT_END ID="F011"> <FILE_CONTENT_START ID="F013" PATH="web/app.ts" LINES="20"> import { formatName, formatPrice } from "./format"; interface Line { item: string; cents: number; qty: number; } /** The greeting banner of the kiosk web screen. */ export function renderGreeting(name: string): string { return `Hello, ${formatName(name)}!`; } /** One receipt line per order line, then the total. */ export function renderReceipt(lines: Line[]): string[] { const rows = lines.map((l) => `${l.qty} x ${l.item} ${formatPrice(l.cents * l.qty)}`); const total = lines.reduce((sum, l) => sum + l.cents * l.qty, 0); return [...rows, `total ${formatPrice(total)}`]; } </FILE_CONTENT_END ID="F013"> <FILE_CONTENT_START ID="F014" PATH="web/format.ts" LINES="10"> /** Price in cents to a display string, e.g. 250 -> "2.50 EUR". */ export function formatPrice(cents: number, currency = "EUR"): string { return `${(cents / 100).toFixed(2)} ${currency}`; } /** The customer's name as the screen shows it. */ export function formatName(name: string): string { return name.trim() === "" ? "guest" : name.trim(); } </FILE_CONTENT_END ID="F014"> ``` stderr: ```text pack bytes=5545 files=11 retention=stdout version=V1 ``` ### dctx pack . --tree-stamps=on exit 0, 5801 bytes, ~1658 est. tokens ```text [DCTX_LLM_CONTEXT_SNAPSHOT_V1] [DIRECTORY:kiosk] <INSTRUCTIONS> 1. Manifest: The <DIRECTORY_TREE> section lists all files. - Each entry: [TYPE] RELATIVE_PATH (ID:UNIQUE_ID, MOD:TIMESTAMP) - TYPE is [D] for directory, [F] for file. 2. Content Access: To read a specific file: - Find its UNIQUE_ID from the directory tree. - Search for the marker: <FILE_CONTENT_START ID="UNIQUE_ID"> - The content is between this marker and </FILE_CONTENT_END ID="UNIQUE_ID"> </INSTRUCTIONS> <DIRECTORY_TREE> [D] (ID:ROOT, MOD:…) [F] .env (ID:F001, MOD:…, SIZE:29) [F] .gitignore (ID:F002, MOD:…, SIZE:8) [F] Cargo.toml (ID:F003, MOD:…, SIZE:185) [F] README.md (ID:F004, MOD:…, SIZE:473) [F] config.toml (ID:F005, MOD:…, SIZE:78) [D] src (ID:D006, MOD:…) [F] src/main.rs (ID:F007, MOD:…, SIZE:331) [F] src/store.rs (ID:F008, MOD:…, SIZE:698) [F] src/util.rs (ID:F009, MOD:…, SIZE:404) [D] tools (ID:D010, MOD:…) [F] tools/report.py (ID:F011, MOD:…, SIZE:484) [D] web (ID:D012, MOD:…) [F] web/app.ts (ID:F013, MOD:…, SIZE:596) [F] web/format.ts (ID:F014, MOD:…, SIZE:350) </DIRECTORY_TREE> <FILE_CONTENT_START ID="F001" PATH=".env" LINES="0"> [Content omitted by pattern rules] </FILE_CONTENT_END ID="F001"> <FILE_CONTENT_START ID="F002" PATH=".gitignore" LINES="2"> target/ </FILE_CONTENT_END ID="F002"> <FILE_CONTENT_START ID="F003" PATH="Cargo.toml" LINES="9"> [package] name = "kiosk" version = "0.1.0" edition = "2021" description = "A tiny order kiosk: the sample project for the dctx website examples." license = "Apache-2.0" [dependencies] </FILE_CONTENT_END ID="F003"> <FILE_CONTENT_START ID="F004" PATH="README.md" LINES="19"> # kiosk A tiny order kiosk. It is the example project that every command on the dctx website runs on. ## Run cargo run -- ada prints `Hello, Ada!` and saves order 1 to `orders/1.tsv`. ## Orders Each order is one tab-separated line: id, item, quantity and a checksum of the item name. `python3 tools/report.py orders/` sums the quantities. ## Configuration `config.toml` holds the currency and the screen title. Secrets live in `.env`, which is never committed. </FILE_CONTENT_END ID="F004"> <FILE_CONTENT_START ID="F005" PATH="config.toml" LINES="7"> [screen] title = "kiosk example" currency = "EUR" [orders] folder = "orders" </FILE_CONTENT_END ID="F005"> <FILE_CONTENT_START ID="F007" PATH="src/main.rs" LINES="11"> //! kiosk: greet a customer, take one order, save it. mod store; mod util; fn main() { let name = std::env::args().nth(1).unwrap_or_else(|| "guest".to_string()); println!("{}", util::greet(&name)); let order = store::Order { id: 1, item: "coffee".to_string(), qty: 2 }; store::save(&order).expect("save order"); } </FILE_CONTENT_END ID="F007"> <FILE_CONTENT_START ID="F008" PATH="src/store.rs" LINES="25"> use std::io; /// One order as the kiosk records it. pub struct Order { pub id: u32, pub item: String, pub qty: u32, } /// Write the order to orders/<id>.tsv. pub fn save(order: &Order) -> io::Result<()> { std::fs::create_dir_all("orders")?; std::fs::write(format!("orders/{}.tsv", order.id), encode(order)) } /// One tab-separated line with a checksum of the item name. fn encode(order: &Order) -> String { format!("{}\t{}\t{}\t{:08x}\n", order.id, order.item, order.qty, checksum(&order.item)) } /// FNV-1a over the bytes of the text. fn checksum(text: &str) -> u32 { text.bytes().fold(0x811c9dc5, |hash, byte| (hash ^ u32::from(byte)).wrapping_mul(0x0100_0193)) } </FILE_CONTENT_END ID="F008"> <FILE_CONTENT_START ID="F009" PATH="src/util.rs" LINES="14"> /// The greeting shown on the kiosk screen. pub fn greet(name: &str) -> String { format!("Hello, {}!", title_case(name)) } /// Upper-case the first letter of a name, leave the rest as typed. pub fn title_case(name: &str) -> String { let mut chars = name.chars(); match chars.next() { Some(first) => first.to_uppercase().chain(chars).collect(), None => String::new(), } } </FILE_CONTENT_END ID="F009"> <FILE_CONTENT_START ID="F011" PATH="tools/report.py" LINES="19"> """Sum the quantities of every saved order: python3 tools/report.py orders/""" import sys from pathlib import Path def read_orders(folder): for path in sorted(Path(folder).glob("*.tsv")): order_id, item, qty, _checksum = path.read_text().rstrip("\n").split("\t") yield order_id, item, int(qty) def main(folder="orders"): total = sum(qty for _, _, qty in read_orders(folder)) print(f"{total} items") if __name__ == "__main__": main(*sys.argv[1:]) </FILE_CONTENT_END ID="F011"> <FILE_CONTENT_START ID="F013" PATH="web/app.ts" LINES="20"> import { formatName, formatPrice } from "./format"; interface Line { item: string; cents: number; qty: number; } /** The greeting banner of the kiosk web screen. */ export function renderGreeting(name: string): string { return `Hello, ${formatName(name)}!`; } /** One receipt line per order line, then the total. */ export function renderReceipt(lines: Line[]): string[] { const rows = lines.map((l) => `${l.qty} x ${l.item} ${formatPrice(l.cents * l.qty)}`); const total = lines.reduce((sum, l) => sum + l.cents * l.qty, 0); return [...rows, `total ${formatPrice(total)}`]; } </FILE_CONTENT_END ID="F013"> <FILE_CONTENT_START ID="F014" PATH="web/format.ts" LINES="10"> /** Price in cents to a display string, e.g. 250 -> "2.50 EUR". */ export function formatPrice(cents: number, currency = "EUR"): string { return `${(cents / 100).toFixed(2)} ${currency}`; } /** The customer's name as the screen shows it. */ export function formatName(name: string): string { return name.trim() === "" ? "guest" : name.trim(); } </FILE_CONTENT_END ID="F014"> ``` stderr: ```text pack bytes=5951 files=11 retention=stdout version=V1 ``` ### dctx pack . --ext rs exit 0, 2345 bytes, ~670 est. tokens ```text [DCTX_LLM_CONTEXT_SNAPSHOT_V1] [DIRECTORY:kiosk] <INSTRUCTIONS> 1. Manifest: The <DIRECTORY_TREE> section lists all files. - Each entry: [TYPE] RELATIVE_PATH (ID:UNIQUE_ID) - TYPE is [D] for directory, [F] for file. 2. Content Access: To read a specific file: - Find its UNIQUE_ID from the directory tree. - Search for the marker: <FILE_CONTENT_START ID="UNIQUE_ID"> - The content is between this marker and </FILE_CONTENT_END ID="UNIQUE_ID"> </INSTRUCTIONS> <DIRECTORY_TREE> [D] (ID:ROOT) [D] src (ID:D001) [F] src/main.rs (ID:F002) [F] src/store.rs (ID:F003) [F] src/util.rs (ID:F004) </DIRECTORY_TREE> <FILE_CONTENT_START ID="F002" PATH="src/main.rs" LINES="11"> //! kiosk: greet a customer, take one order, save it. mod store; mod util; fn main() { let name = std::env::args().nth(1).unwrap_or_else(|| "guest".to_string()); println!("{}", util::greet(&name)); let order = store::Order { id: 1, item: "coffee".to_string(), qty: 2 }; store::save(&order).expect("save order"); } </FILE_CONTENT_END ID="F002"> <FILE_CONTENT_START ID="F003" PATH="src/store.rs" LINES="25"> use std::io; /// One order as the kiosk records it. pub struct Order { pub id: u32, pub item: String, pub qty: u32, } /// Write the order to orders/<id>.tsv. pub fn save(order: &Order) -> io::Result<()> { std::fs::create_dir_all("orders")?; std::fs::write(format!("orders/{}.tsv", order.id), encode(order)) } /// One tab-separated line with a checksum of the item name. fn encode(order: &Order) -> String { format!("{}\t{}\t{}\t{:08x}\n", order.id, order.item, order.qty, checksum(&order.item)) } /// FNV-1a over the bytes of the text. fn checksum(text: &str) -> u32 { text.bytes().fold(0x811c9dc5, |hash, byte| (hash ^ u32::from(byte)).wrapping_mul(0x0100_0193)) } </FILE_CONTENT_END ID="F003"> <FILE_CONTENT_START ID="F004" PATH="src/util.rs" LINES="14"> /// The greeting shown on the kiosk screen. pub fn greet(name: &str) -> String { format!("Hello, {}!", title_case(name)) } /// Upper-case the first letter of a name, leave the rest as typed. pub fn title_case(name: &str) -> String { let mut chars = name.chars(); match chars.next() { Some(first) => first.to_uppercase().chain(chars).collect(), None => String::new(), } } </FILE_CONTENT_END ID="F004"> ``` stderr: ```text pack bytes=2345 files=3 retention=stdout version=V1 ``` ### dctx pack . --debug-ignored exit 0, 5670 bytes, ~1620 est. tokens ```text [DCTX_LLM_CONTEXT_SNAPSHOT_V1] [DIRECTORY:kiosk] <INSTRUCTIONS> 1. Manifest: The <DIRECTORY_TREE> section lists all files. - Each entry: [TYPE] RELATIVE_PATH (ID:UNIQUE_ID) - TYPE is [D] for directory, [F] for file. 2. Content Access: To read a specific file: - Find its UNIQUE_ID from the directory tree. - Search for the marker: <FILE_CONTENT_START ID="UNIQUE_ID"> - The content is between this marker and </FILE_CONTENT_END ID="UNIQUE_ID"> </INSTRUCTIONS> <DIRECTORY_TREE> [D] (ID:ROOT) [F] .env (ID:F001) [F] .gitignore (ID:F002) [F] Cargo.toml (ID:F003) [F] README.md (ID:F004) [F] config.toml (ID:F005) [D] src (ID:D006) [F] src/main.rs (ID:F007) [F] src/store.rs (ID:F008) [F] src/util.rs (ID:F009) [D] target [IGNORED] (ID:D010) [D] target/debug [IGNORED] (ID:D011) [F] target/debug/kiosk.d [IGNORED] (ID:F012) [D] tools (ID:D013) [F] tools/report.py (ID:F014) [D] web (ID:D015) [F] web/app.ts (ID:F016) [F] web/format.ts (ID:F017) </DIRECTORY_TREE> <FILE_CONTENT_START ID="F001" PATH=".env" LINES="0"> [Content omitted by pattern rules] </FILE_CONTENT_END ID="F001"> <FILE_CONTENT_START ID="F002" PATH=".gitignore" LINES="2"> target/ </FILE_CONTENT_END ID="F002"> <FILE_CONTENT_START ID="F003" PATH="Cargo.toml" LINES="9"> [package] name = "kiosk" version = "0.1.0" edition = "2021" description = "A tiny order kiosk: the sample project for the dctx website examples." license = "Apache-2.0" [dependencies] </FILE_CONTENT_END ID="F003"> <FILE_CONTENT_START ID="F004" PATH="README.md" LINES="19"> # kiosk A tiny order kiosk. It is the example project that every command on the dctx website runs on. ## Run cargo run -- ada prints `Hello, Ada!` and saves order 1 to `orders/1.tsv`. ## Orders Each order is one tab-separated line: id, item, quantity and a checksum of the item name. `python3 tools/report.py orders/` sums the quantities. ## Configuration `config.toml` holds the currency and the screen title. Secrets live in `.env`, which is never committed. </FILE_CONTENT_END ID="F004"> <FILE_CONTENT_START ID="F005" PATH="config.toml" LINES="7"> [screen] title = "kiosk example" currency = "EUR" [orders] folder = "orders" </FILE_CONTENT_END ID="F005"> <FILE_CONTENT_START ID="F007" PATH="src/main.rs" LINES="11"> //! kiosk: greet a customer, take one order, save it. mod store; mod util; fn main() { let name = std::env::args().nth(1).unwrap_or_else(|| "guest".to_string()); println!("{}", util::greet(&name)); let order = store::Order { id: 1, item: "coffee".to_string(), qty: 2 }; store::save(&order).expect("save order"); } </FILE_CONTENT_END ID="F007"> <FILE_CONTENT_START ID="F008" PATH="src/store.rs" LINES="25"> use std::io; /// One order as the kiosk records it. pub struct Order { pub id: u32, pub item: String, pub qty: u32, } /// Write the order to orders/<id>.tsv. pub fn save(order: &Order) -> io::Result<()> { std::fs::create_dir_all("orders")?; std::fs::write(format!("orders/{}.tsv", order.id), encode(order)) } /// One tab-separated line with a checksum of the item name. fn encode(order: &Order) -> String { format!("{}\t{}\t{}\t{:08x}\n", order.id, order.item, order.qty, checksum(&order.item)) } /// FNV-1a over the bytes of the text. fn checksum(text: &str) -> u32 { text.bytes().fold(0x811c9dc5, |hash, byte| (hash ^ u32::from(byte)).wrapping_mul(0x0100_0193)) } </FILE_CONTENT_END ID="F008"> <FILE_CONTENT_START ID="F009" PATH="src/util.rs" LINES="14"> /// The greeting shown on the kiosk screen. pub fn greet(name: &str) -> String { format!("Hello, {}!", title_case(name)) } /// Upper-case the first letter of a name, leave the rest as typed. pub fn title_case(name: &str) -> String { let mut chars = name.chars(); match chars.next() { Some(first) => first.to_uppercase().chain(chars).collect(), None => String::new(), } } </FILE_CONTENT_END ID="F009"> <FILE_CONTENT_START ID="F014" PATH="tools/report.py" LINES="19"> """Sum the quantities of every saved order: python3 tools/report.py orders/""" import sys from pathlib import Path def read_orders(folder): for path in sorted(Path(folder).glob("*.tsv")): order_id, item, qty, _checksum = path.read_text().rstrip("\n").split("\t") yield order_id, item, int(qty) def main(folder="orders"): total = sum(qty for _, _, qty in read_orders(folder)) print(f"{total} items") if __name__ == "__main__": main(*sys.argv[1:]) </FILE_CONTENT_END ID="F014"> <FILE_CONTENT_START ID="F016" PATH="web/app.ts" LINES="20"> import { formatName, formatPrice } from "./format"; interface Line { item: string; cents: number; qty: number; } /** The greeting banner of the kiosk web screen. */ export function renderGreeting(name: string): string { return `Hello, ${formatName(name)}!`; } /** One receipt line per order line, then the total. */ export function renderReceipt(lines: Line[]): string[] { const rows = lines.map((l) => `${l.qty} x ${l.item} ${formatPrice(l.cents * l.qty)}`); const total = lines.reduce((sum, l) => sum + l.cents * l.qty, 0); return [...rows, `total ${formatPrice(total)}`]; } </FILE_CONTENT_END ID="F016"> <FILE_CONTENT_START ID="F017" PATH="web/format.ts" LINES="10"> /** Price in cents to a display string, e.g. 250 -> "2.50 EUR". */ export function formatPrice(cents: number, currency = "EUR"): string { return `${(cents / 100).toFixed(2)} ${currency}`; } /** The customer's name as the screen shows it. */ export function formatName(name: string): string { return name.trim() === "" ? "guest" : name.trim(); } </FILE_CONTENT_END ID="F017"> ``` stderr: ```text pack bytes=5670 files=12 retention=stdout version=V1 ``` ### dctx pack . --for 'greet store' --budget 800 exit 0, 822 bytes, ~235 est. tokens ```text # dctx pack --for budget=800 terms=2 ## find greet s:src/util.rs#greet fn L2-4 s:web/app.ts#renderGreeting fn L10-12 ## find store s:src/store.rs#Order struct L4-8 s:src/store.rs#checksum fn L22-24 s:src/store.rs#encode fn L17-19 ## neighbors s:src/util.rs#greet calls:in:s:src/main.rs#main fn src/main.rs L7 calls:out:s:src/util.rs#title_case fn src/util.rs contains:in:m:src/util.rs module src/util.rs ## neighbors s:src/store.rs#Order contains:in:m:src/store.rs module src/store.rs ## read s:src/util.rs#greet s:src/util.rs#greet fn src/util.rs pub fn greet(name: &str) -> String { format!("Hello, {}!", title_case(name)) } ## read s:src/store.rs#Order s:src/store.rs#Order struct src/store.rs pub struct Order { pub id: u32, pub item: String, pub qty: u32, } # end body_tokens=223 budget=800 dropped=0 ``` ### dctx map map src/util.rs --depth 2 exit 0, 74 bytes, ~22 est. tokens ```text # kiosk map s:src/util.rs#greet fn L2-4 s:src/util.rs#title_case fn L7-13 ``` ### dctx map find greet exit 0, 79 bytes, ~23 est. tokens ```text # kiosk find s:src/util.rs#greet fn L2-4 s:web/app.ts#renderGreeting fn L10-12 ``` ### dctx map read 's:src/util.rs#greet' exit 0, 131 bytes, ~38 est. tokens ```text # kiosk read s:src/util.rs#greet fn src/util.rs pub fn greet(name: &str) -> String { format!("Hello, {}!", title_case(name)) } ``` ### dctx map neighbors 's:src/util.rs#greet' --edge calls --dir in exit 0, 64 bytes, ~19 est. tokens ```text # kiosk neighbors calls:in:s:src/main.rs#main fn src/main.rs L7 ``` ### dctx map explain 's:src/util.rs#greet' exit 0, 51 bytes, ~15 est. tokens ```text # kiosk explain s:src/util.rs#greet fn src/util.rs ``` ### dctx map skeleton src/store.rs exit 0, 280 bytes, ~80 est. tokens ```text # kiosk skeleton m:src/store.rs module L1-24 src/store.rs s:src/store.rs#Order struct L4-8 pub struct Order s:src/store.rs#save fn L11-14 pub fn save(order: &Order) s:src/store.rs#encode fn L17-19 fn encode(order: &Order) s:src/store.rs#checksum fn L22-24 fn checksum(text: &str) ``` ### dctx map grep example -i exit 0, 380 bytes, ~109 est. tokens ```text # kiosk grep s:Cargo.toml#package.description fn Cargo.toml L5: description = "A tiny order kiosk: the sample project for the dctx website examples." d:README.md#kiosk heading README.md L3: A tiny order kiosk. It is the example project that every command on the dctx website runs on. s:config.toml#screen.title fn config.toml L2: title = "kiosk example" 3 hits in 3 symbols ``` ### dctx map hubs --limit 10 exit 0, 519 bytes, ~149 est. tokens ```text # kiosk hubs s:src/store.rs#checksum fn src/store.rs 1 s:src/store.rs#encode fn src/store.rs 1 s:src/store.rs#save fn src/store.rs 1 s:src/util.rs#greet fn src/util.rs 1 s:src/util.rs#title_case fn src/util.rs 1 s:tools/report.py#main fn tools/report.py 1 s:tools/report.py#read_orders fn tools/report.py 1 s:web/format.ts#formatName fn web/format.ts 1 s:web/format.ts#formatPrice fn web/format.ts 1 ./ 4 files 12 symbols assets/ 1 files 0 symbols src/ 3 files 7 symbols tools/ 1 files 2 symbols web/ 2 files 5 symbols ``` ### dctx map path 's:src/main.rs#main' 's:src/store.rs#save' exit 0, 99 bytes, ~29 est. tokens ```text # kiosk path start s:src/main.rs#main fn src/main.rs calls:out s:src/store.rs#save fn src/store.rs ``` ### dctx map find greet --json exit 0, 745 bytes, ~213 est. tokens ```text {"v":2,"place":"kiosk","verb":"find","freshness":{"mode":"strict","state":"verified"},"precision":{"coverage":"structural","completion":"complete","parser":"dctx-structural/3"},"records":[{"id":"s:src/util.rs#greet","kind":"fn","path":"src/util.rs","lines":[2,4],"summary":"The greeting shown on the kiosk screen.","summary_source":"doc","signature":null,"span":null,"source_utf8":null,"edge":null,"direction":null,"target":null,"confidence":null},{"id":"s:web/app.ts#renderGreeting","kind":"fn","path":"web/app.ts","lines":[10,12],"summary":"The greeting banner of the kiosk web screen.","summary_source":"doc","signature":null,"span":null,"source_utf8":null,"edge":null,"direction":null,"target":null,"confidence":null}],"more":0,"next":null} ``` ### dctx map neighbors 's:src/util.rs#greet' --edge calls --dir in --json exit 0, 365 bytes, ~105 est. tokens ```text {"v":2,"place":"kiosk","verb":"neighbors","freshness":{"mode":"strict","state":"verified"},"precision":{"coverage":"structural","completion":"complete","parser":"dctx-structural/3"},"records":[{"id":"calls:in:s:src/main.rs#main","kind":"fn","path":"src/main.rs","lines":[5,10],"edge":"calls","direction":"in","confidence":"name","sites":[7]}],"more":0,"next":null} ``` ### dctx map read 's:src/util.rs#greet' --json exit 0, 561 bytes, ~161 est. tokens ```text {"v":2,"place":"kiosk","verb":"read","freshness":{"mode":"strict","state":"verified"},"precision":{"coverage":"syntax","completion":"complete","parser":"dctx-lex-rust/syn-3.0.9"},"records":[{"id":"s:src/util.rs#greet","kind":"fn","path":"src/util.rs","lines":[2,4],"summary":"The greeting shown on the kiosk screen.","summary_source":"doc","signature":null,"span":[44,126],"source_utf8":"pub fn greet(name: &str) -> String {\n format!(\"Hello, {}!\", title_case(name))\n}","edge":null,"direction":null,"target":null,"confidence":null}],"more":0,"next":null} ``` ### dctx map find greet --json --meta exit 0, 865 bytes, ~248 est. tokens ```text {"v":2,"place":"kiosk","snapshot":"v1:sha256:1de480dbf3f559eb25ca11d9bad2556f8239ae97916d084ce17abafb02916da3:6840","generation":1,"verb":"find","freshness":{"mode":"strict","state":"verified","age_s":…},"precision":{"coverage":"structural","completion":"complete","parser":"dctx-structural/3"},"records":[{"id":"s:src/util.rs#greet","kind":"fn","path":"src/util.rs","lines":[2,4],"summary":"The greeting shown on the kiosk screen.","summary_source":"doc","signature":null,"span":null,"source_utf8":null,"edge":null,"direction":null,"target":null,"confidence":null},{"id":"s:web/app.ts#renderGreeting","kind":"fn","path":"web/app.ts","lines":[10,12],"summary":"The greeting banner of the kiosk web screen.","summary_source":"doc","signature":null,"span":null,"source_utf8":null,"edge":null,"direction":null,"target":null,"confidence":null}],"more":0,"next":null} ``` ### dctx map export --format mermaid exit 0, 1542 bytes, ~441 est. tokens ```text flowchart LR n0["d:README.md#Configuration"] n1["d:README.md#Orders"] n2["d:README.md#Run"] n3["d:README.md#kiosk"] n4["m:.gitignore"] n5["m:Cargo.toml"] n6["m:README.md"] n7["m:assets/logo.png"] n8["m:config.toml"] n9["m:src/main.rs"] n10["m:src/store.rs"] n11["m:src/util.rs"] n12["m:tools/report.py"] n13["m:web/app.ts"] n14["m:web/format.ts"] n15["s:Cargo.toml#dependencies"] n16["s:Cargo.toml#package"] n17["s:Cargo.toml#package.description"] n18["s:Cargo.toml#package.edition"] n19["s:Cargo.toml#package.license"] n20["s:Cargo.toml#package.name"] n21["s:Cargo.toml#package.version"] n22["s:config.toml#orders"] n23["s:config.toml#orders.folder"] n24["s:config.toml#screen"] n25["s:config.toml#screen.currency"] n26["s:config.toml#screen.title"] n27["s:src/main.rs#main"] n28["s:src/store.rs#Order"] n29["s:src/store.rs#checksum"] n30["s:src/store.rs#encode"] n31["s:src/store.rs#save"] n32["s:src/util.rs#greet"] n33["s:src/util.rs#title_case"] n34["s:tools/report.py#main"] n35["s:tools/report.py#read_orders"] n36["s:web/app.ts#Line"] n37["s:web/app.ts#renderGreeting"] n38["s:web/app.ts#renderReceipt"] n39["s:web/format.ts#formatName"] n40["s:web/format.ts#formatPrice"] n9 -->|imports| n10 n9 -->|imports| n11 n12 -->|calls| n34 n13 -->|imports| n39 n13 -->|imports| n40 n27 -->|calls| n31 n27 -->|calls| n32 n30 -->|calls| n29 n31 -->|calls| n30 n32 -->|calls| n33 n34 -->|calls| n35 n37 -->|calls| n39 n38 -->|calls| n40 ``` ### dctx map export --format json exit 0, 7527 bytes, ~2151 est. tokens ```text {"nodes":[ {"id":"d:README.md#Configuration","kind":"heading","path":"README.md","lines":[16,18]}, {"id":"d:README.md#Orders","kind":"heading","path":"README.md","lines":[11,15]}, {"id":"d:README.md#Run","kind":"heading","path":"README.md","lines":[5,10]}, {"id":"d:README.md#kiosk","kind":"heading","path":"README.md","lines":[1,18]}, {"id":"m:.gitignore","kind":"module","path":".gitignore","lines":[1,1]}, {"id":"m:Cargo.toml","kind":"module","path":"Cargo.toml","lines":[1,8]}, {"id":"m:README.md","kind":"module","path":"README.md","lines":[1,18]}, {"id":"m:assets/logo.png","kind":"module","path":"assets/logo.png","lines":[1,3]}, {"id":"m:config.toml","kind":"module","path":"config.toml","lines":[1,6]}, {"id":"m:src/main.rs","kind":"module","path":"src/main.rs","lines":[1,10]}, {"id":"m:src/store.rs","kind":"module","path":"src/store.rs","lines":[1,24]}, {"id":"m:src/util.rs","kind":"module","path":"src/util.rs","lines":[1,13]}, {"id":"m:tools/report.py","kind":"module","path":"tools/report.py","lines":[1,18]}, {"id":"m:web/app.ts","kind":"module","path":"web/app.ts","lines":[1,19]}, {"id":"m:web/format.ts","kind":"module","path":"web/format.ts","lines":[1,9]}, {"id":"s:Cargo.toml#dependencies","kind":"struct","path":"Cargo.toml","lines":[8,8]}, {"id":"s:Cargo.toml#package","kind":"struct","path":"Cargo.toml","lines":[1,6]}, {"id":"s:Cargo.toml#package.description","kind":"fn","path":"Cargo.toml","lines":[5,5]}, {"id":"s:Cargo.toml#package.edition","kind":"fn","path":"Cargo.toml","lines":[4,4]}, {"id":"s:Cargo.toml#package.license","kind":"fn","path":"Cargo.toml","lines":[6,6]}, {"id":"s:Cargo.toml#package.name","kind":"fn","path":"Cargo.toml","lines":[2,2]}, {"id":"s:Cargo.toml#package.version","kind":"fn","path":"Cargo.toml","lines":[3,3]}, {"id":"s:config.toml#orders","kind":"struct","path":"config.toml","lines":[5,6]}, {"id":"s:config.toml#orders.folder","kind":"fn","path":"config.toml","lines":[6,6]}, {"id":"s:config.toml#screen","kind":"struct","path":"config.toml","lines":[1,3]}, {"id":"s:config.toml#screen.currency","kind":"fn","path":"config.toml","lines":[3,3]}, {"id":"s:config.toml#screen.title","kind":"fn","path":"config.toml","lines":[2,2]}, {"id":"s:src/main.rs#main","kind":"fn","path":"src/main.rs","lines":[5,10]}, {"id":"s:src/store.rs#Order","kind":"struct","path":"src/store.rs","lines":[4,8]}, {"id":"s:src/store.rs#checksum","kind":"fn","path":"src/store.rs","lines":[22,24]}, {"id":"s:src/store.rs#encode","kind":"fn","path":"src/store.rs","lines":[17,19]}, {"id":"s:src/store.rs#save","kind":"fn","path":"src/store.rs","lines":[11,14]}, {"id":"s:src/util.rs#greet","kind":"fn","path":"src/util.rs","lines":[2,4]}, {"id":"s:src/util.rs#title_case","kind":"fn","path":"src/util.rs","lines":[7,13]}, {"id":"s:tools/report.py#main","kind":"fn","path":"tools/report.py","lines":[12,14]}, {"id":"s:tools/report.py#read_orders","kind":"fn","path":"tools/report.py","lines":[6,9]}, {"id":"s:web/app.ts#Line","kind":"interface","path":"web/app.ts","lines":[3,7]}, {"id":"s:web/app.ts#renderGreeting","kind":"fn","path":"web/app.ts","lines":[10,12]}, {"id":"s:web/app.ts#renderReceipt","kind":"fn","path":"web/app.ts","lines":[15,19]}, {"id":"s:web/format.ts#formatName","kind":"fn","path":"web/format.ts","lines":[7,9]}, {"id":"s:web/format.ts#formatPrice","kind":"fn","path":"web/format.ts","lines":[2,4]}],"edges":[ {"src":"m:Cargo.toml","edge":"contains","dst":"s:Cargo.toml#dependencies","confidence":"exact"}, {"src":"m:Cargo.toml","edge":"contains","dst":"s:Cargo.toml#package","confidence":"exact"}, {"src":"m:Cargo.toml","edge":"contains","dst":"s:Cargo.toml#package.description","confidence":"exact"}, {"src":"m:Cargo.toml","edge":"contains","dst":"s:Cargo.toml#package.edition","confidence":"exact"}, {"src":"m:Cargo.toml","edge":"contains","dst":"s:Cargo.toml#package.license","confidence":"exact"}, {"src":"m:Cargo.toml","edge":"contains","dst":"s:Cargo.toml#package.name","confidence":"exact"}, {"src":"m:Cargo.toml","edge":"contains","dst":"s:Cargo.toml#package.version","confidence":"exact"}, {"src":"m:README.md","edge":"contains","dst":"d:README.md#Configuration","confidence":"exact"}, {"src":"m:README.md","edge":"contains","dst":"d:README.md#Orders","confidence":"exact"}, {"src":"m:README.md","edge":"contains","dst":"d:README.md#Run","confidence":"exact"}, {"src":"m:README.md","edge":"contains","dst":"d:README.md#kiosk","confidence":"exact"}, {"src":"m:config.toml","edge":"contains","dst":"s:config.toml#orders","confidence":"exact"}, {"src":"m:config.toml","edge":"contains","dst":"s:config.toml#orders.folder","confidence":"exact"}, {"src":"m:config.toml","edge":"contains","dst":"s:config.toml#screen","confidence":"exact"}, {"src":"m:config.toml","edge":"contains","dst":"s:config.toml#screen.currency","confidence":"exact"}, {"src":"m:config.toml","edge":"contains","dst":"s:config.toml#screen.title","confidence":"exact"}, {"src":"m:src/main.rs","edge":"contains","dst":"s:src/main.rs#main","confidence":"exact"}, {"src":"m:src/main.rs","edge":"imports","dst":"m:src/store.rs","confidence":"exact"}, {"src":"m:src/main.rs","edge":"imports","dst":"m:src/util.rs","confidence":"exact"}, {"src":"m:src/store.rs","edge":"contains","dst":"s:src/store.rs#Order","confidence":"exact"}, {"src":"m:src/store.rs","edge":"contains","dst":"s:src/store.rs#checksum","confidence":"exact"}, {"src":"m:src/store.rs","edge":"contains","dst":"s:src/store.rs#encode","confidence":"exact"}, {"src":"m:src/store.rs","edge":"contains","dst":"s:src/store.rs#save","confidence":"exact"}, {"src":"m:src/util.rs","edge":"contains","dst":"s:src/util.rs#greet","confidence":"exact"}, {"src":"m:src/util.rs","edge":"contains","dst":"s:src/util.rs#title_case","confidence":"exact"}, {"src":"m:tools/report.py","edge":"calls","dst":"s:tools/report.py#main","confidence":"name"}, {"src":"m:tools/report.py","edge":"contains","dst":"s:tools/report.py#main","confidence":"exact"}, {"src":"m:tools/report.py","edge":"contains","dst":"s:tools/report.py#read_orders","confidence":"exact"}, {"src":"m:web/app.ts","edge":"contains","dst":"s:web/app.ts#Line","confidence":"exact"}, {"src":"m:web/app.ts","edge":"contains","dst":"s:web/app.ts#renderGreeting","confidence":"exact"}, {"src":"m:web/app.ts","edge":"contains","dst":"s:web/app.ts#renderReceipt","confidence":"exact"}, {"src":"m:web/app.ts","edge":"imports","dst":"s:web/format.ts#formatName","confidence":"exact"}, {"src":"m:web/app.ts","edge":"imports","dst":"s:web/format.ts#formatPrice","confidence":"exact"}, {"src":"m:web/format.ts","edge":"contains","dst":"s:web/format.ts#formatName","confidence":"exact"}, {"src":"m:web/format.ts","edge":"contains","dst":"s:web/format.ts#formatPrice","confidence":"exact"}, {"src":"s:src/main.rs#main","edge":"calls","dst":"s:src/store.rs#save","confidence":"name"}, {"src":"s:src/main.rs#main","edge":"calls","dst":"s:src/util.rs#greet","confidence":"name"}, {"src":"s:src/store.rs#encode","edge":"calls","dst":"s:src/store.rs#checksum","confidence":"name"}, {"src":"s:src/store.rs#save","edge":"calls","dst":"s:src/store.rs#encode","confidence":"name"}, {"src":"s:src/util.rs#greet","edge":"calls","dst":"s:src/util.rs#title_case","confidence":"name"}, {"src":"s:tools/report.py#main","edge":"calls","dst":"s:tools/report.py#read_orders","confidence":"name"}, {"src":"s:web/app.ts#renderGreeting","edge":"calls","dst":"s:web/format.ts#formatName","confidence":"name"}, {"src":"s:web/app.ts#renderReceipt","edge":"calls","dst":"s:web/format.ts#formatPrice","confidence":"name"}]} ``` ### dctx map read m:nope.rs exit 1, 28 bytes, ~8 est. tokens ```text # kiosk read gone m:nope.rs ``` stderr: ```text [no] Error: map: m:nope.rs is not in the index hint: the file may be missing, ignored, sensitive or renamed; list current ids with `dctx map find <name>` ``` ### dctx map read m:.env exit 1, 25 bytes, ~8 est. tokens ```text # kiosk read gone m:.env ``` stderr: ```text [no] Error: map: m:.env is not in the index hint: the file may be missing, ignored, sensitive or renamed; list current ids with `dctx map find <name>` ``` ### dctx map find '' exit 2, 0 bytes, ~0 est. tokens ```text ``` stderr: ```text [no] Error: map: this verb requires a target; next: correct the request or source input and retry; use dctx map --help for options hint: pass a non-empty name or phrase, for example: dctx map find alpha ``` ### dctx template build default.dctx_template exit 0, 139 bytes, ~40 est. tokens ```text template source_version=1 plan_bytes=2191 digest=5fdd4d1fd3ef127241bc661a6057dad7cf812b0081eec51e58b2bf09f3b802fb views=1 retention=stdout ``` ### dctx template build stamped.dctx_template exit 0, 139 bytes, ~40 est. tokens ```text template source_version=1 plan_bytes=2243 digest=e55e481eef9bec67a82232802068e28037389d0bdd1efbce5e3dcda73a327364 views=1 retention=stdout ```