v0.12.1

[0.12.1] — 2026-06-16

Added

• CI matrix (.github/workflows/ci.yml): on every push/PR to
  develop/main, the suite runs across
  {ubuntu, macos, windows} × {3.10, 3.13} with ruff check,
  ruff format --check, and pytest. Windows is continue-on-error
  (best-effort for 1.0.0); Linux/macOS are blocking. This turns
  cross-platform correctness from opinion into a checked fact.

Changed

• Tier-1 grammars now install offline; Tier-2 moves behind
  dekko[all]. A default pip install dekko ships the nine Tier-1
  languages (C, C++, Go, Java, JavaScript, Python, Rust, TypeScript,
  TSX) as individual, pinned grammar packages, so mapping them makes
  no network call — no more runtime grammar download, offline
  failure, or supply-chain surface from the catch-all pack. The ~55
  generic Tier-2 languages now require pip install dekko[all], which
  pulls in tree-sitter-language-pack; without it, a Tier-2 file is
  skipped with a "needs dekko[all]" note rather than parsed. Grammar
  resolution moved behind a new grammars.get_grammar seam (cached, so
  each grammar loads once). Map output for any installed grammar is
  unchanged.
• Release workflow is hardened around the version tag. release.yml
  still fires only on a v* tag, but now rejects a tag whose version
  does not match the built wheel (catches a forgotten version bump), and
  the publish job carries an explicit refs/tags/v* guard so it can
  never run off a non-release ref. The workflow header documents the
  gating and the one-time PyPI trusted-publisher prerequisite.
• dekko diff no longer shells out to tar. The earlier-rev export
  now captures git archive --format=tar and extracts it with the
  stdlib tarfile module instead of piping to an external tar
  binary, removing an undocumented POSIX dependency (a step toward
  Windows support). Extraction refuses path traversal (the data
  filter on 3.12+, an explicit guard on 3.10/3.11). Map output is
  unchanged.

Fixed

• Windows: the claude CLI is now invoked by its resolved full path
  rather than the bare name, so the plugin/MCP install and uninstall
  commands launch a claude.cmd shim that subprocess would otherwise
  fail to start. No change on macOS/Linux.
• Windows: the session ledger now finds its transcript. The
  ~/.claude/projects directory key now encodes backslashes and the
  drive colon (not just POSIX /), matching Claude Code's per-platform
  naming. Still best-effort — a miss degrades to an empty ledger.

Documentation

• README install & platform pass: the install section now states the
  offline Tier-1 footprint, points to pip install dekko[all] for the
  Tier-2 languages, and notes the tested-platforms line (macOS/Linux;
  Windows best-effort via CI). The "Language support" and "Development"
  sections match the new packaging.

[0.11.0] — 2026-06-16

Active Context Layer

dekko grows from a pull context server into a session-aware push
layer: it ranks context by the live task, knows what the agent already
holds, and can deliver orientation through opt-in Claude Code hooks.

Added

• Task-aware ranking (--task) on lean, workset, and context
  (and the matching MCP tools): a free-text task description is blended
  with structural centrality and the working diff so the most relevant
  code survives a tight budget. Lexical and dependency-free; output is
  byte-for-byte unchanged when no task is given. New relevance module
  with a pluggable Scorer (lexical now, embeddings a future drop-in).
• dekko lean --dense (and MCP dense): keeps full signatures only
  on the most central symbols, names for the rest — the tersest
  whole-repo map.
• dekko ledger (and MCP ledger): projects the Claude Code session
  transcript into "what is already in context" — files read, symbols
  seen, and real tokens consumed (from the transcript's usage). dekko
  persists no session state of its own, so it also sees direct reads.
• dekko hooks install|uninstall|run: opt-in push hooks merged into
  project .claude/settings.json — session-start (steering preamble +
  budget-capped lean map), prompt-submit (relevance-ranked pointer to
  files not yet in context), and pre-read (non-blocking advisory to
  outline a large file first, permissionDecision: "defer"). Every hook
  is fail-silent and individually toggleable; uninstall touches only
  dekko's entries.
• Density metric (FR-D3): Meter and the lean report now expose
  signals and tokens-per-signal, so output cost can be measured against
  coverage. A benchmarks/ harness records the baseline reduction (dekko
  mapping its own source: ~92% fewer tokens than whole-file reads).

[0.10.0] — 2026-06-16

Context & token management for agents: every list-shaped command can now
be held to a token budget, and new commands (outline, lean,
workset, orient) let an agent orient and scope a change without
reading whole files.

Added

• dekko lean: a budget-capped, whole-repo navigation map for agents —
  the middle ground between dekko summary (~400 tokens) and MAP.md
  (tens of thousands). Every in-scope file with its purpose, each
  symbol's name (signatures on the most central, by fan-in × churn),
  the coarse module-dependency edges, and an optional architecture
  diagram, all shed in a fixed priority order to fit a hard token cap
  that scales with repo size. The header reports what was elided and the
  command to recover it. Prints to stdout, writes a file with
  --output (e.g. .dekko/LEAN.md, gitignored like other maps), or
  emits --json; also an MCP lean tool.
• Universal token budgeting across query, unused, affected, and
  context. Each command now ranks its rows by relevance (production
  before tests, more-connected before leaves), keeps as many as fit, and
  self-meters: text output carries a (~N tokens · M of T omitted · raise --budget) footer and JSON carries a matching meta object. A
  --budget flag caps query/unused/affected; the relation MCP
  tools gained an equivalent budget argument.
• dekko outline <path|dir>: a file's (or directory's) structure —
  module purpose, each symbol's signature, doc first line, and line
  number, with no bodies — at roughly a tenth the cost of reading the
  file, plus a full ≈ X · outline ≈ Y (P%) size frame. Exposed as an
  MCP tool whose description steers agents to prefer it before reading a
  file.
• dekko workset [REV] | --symbol NAME: one budgeted bundle for a whole
  change — the impacted test files (with a ready-to-paste pytest hint),
  outlines of the touched files, and context packs for the most central
  touched symbols. A single shared budget (default 6000) trims
  detail-first so breadth survives a tight cap; --packs controls how
  many symbols get a pack. Also available as an MCP tool.
• dekko orient: an opt-in orientation layer. With no arguments it
  prints a steering digest (a budgeted repo summary plus pointers to the
  query surface); with --read PATH it emits a one-line nudge to outline
  a file before reading it, but only when the file is large enough to be
  worth it, and never blocks. Ships with a dekko-orient skill and
  documented (opt-in) SessionStart / PreToolUse hook snippets.
• Optional accurate token counting for every --budget cap and the lean
  map: pip install dekko[tokenizer] adds tiktoken (o200k_base) and
  dekko uses it automatically, replacing the default ~4 chars/token
  estimate (which systematically under-counts code). The default install
  is unchanged — no dependency, byte-stable output. DEKKO_TOKENIZER= chars4 forces the estimate back on for reproducible output even when
  the extra is installed.

Changed

• Internal: shared helpers were promoted for reuse by the lean map —
  textutil.dir_of, summary.file_churn, and export.dir_graph (the
  directory-level graph behind both MAP.md's diagram and the lean map's
  module edges). No user-visible change.

[0.9.0] — 2026-06-14

Track B: the human-readable map. MAP.md is now a navigable document —
an overview with rankings and an architecture diagram, sharded pages for
large repos, hotspots and a freshness line — plus a standalone
interactive HTML export.

Added

• MAP.md now renders purpose lines from the v3 schema's doc
  fields: the Contents index shows each file's module purpose after
  its symbol count, file section headers carry the same purpose, and
  each symbol block shows its docstring first line under the
  signature. Files with no doc, and parse-error files, render cleanly
  with no placeholder noise.
• MAP.md now opens with an ## Overview section: a per-directory
  rollup table (files, symbols, internal vs. cross-directory call
  edges, purpose), linked load-bearing and orchestrator rankings,
  entry points, and parse errors. It is the markdown skin of
  dekko summary — one computation, two renderings — so the digest
  and the document always agree. Cross-directory edge counts are the
  new "coupling at a glance" number.
• The MAP.md Overview now embeds a mermaid architecture diagram,
  rendered natively by GitHub (no toolchain or network). A scale guard
  tiers it down as the repo grows: the file-scope graph while it fits
  under --max-nodes (300), then a directory-scope collapse, then a
  one-line pointer to dekko export --format mermaid. MAP.md and
  dekko export share one graph generator.
• dekko map --shard auto|always|never (default auto): large maps
  split into per-directory map/<dir-slug>.md pages with MAP.md as
  the index (Overview + linked TOC); auto shards once the single
  document would exceed ~4,000 lines or 200 KB. Anchor ids are global,
  so a symbol's link is identical in either shape. Stale pages from a
  previous run (e.g. a renamed directory) are cleared before writing.
• The MAP.md Overview gained a Largest files list (linked, by
  symbol count; also shown by dekko summary) and a best-effort
  Hotspots table — recent git churn weighted by fan-in, surfacing
  the files where a change spreads furthest. The hotspots section is
  omitted silently on non-git roots or any git failure.
• The MAP.md header now carries a freshness/trust line —
  Mapped N files in T ms (cache: X reused / Y parsed) — so a reader
  can see at a glance how the map was built.
• dekko map --order path|name|fan-in (default path): order the
  MAP.md file sections by path (today's walk order), base filename,
  or fan-in (most depended-on first). fan-in also orders the symbols
  within each file by inbound degree — load-bearing first.
• dekko export --format html: a single self-contained, interactive
  HTML file (default .dekko/map.html) — collapsible directory tree,
  client-side substring search over names/qualnames/paths, and a symbol
  pane with signature, doc, and clickable callers/callees showing
  call-site lines. Test symbols are de-emphasized; the header carries
  the summary stats. No dependencies, no network, no build step; a size
  guard refuses maps too large to inline (exit 2, like --max-nodes).
• dekko export --output PATH writes any format to a file instead of
  stdout (html defaults to .dekko/map.html).

Changed

• signature() moved from render_md to textutil so renderers and
  the summary/overview share it without an import cycle. Internal
  only; output is unchanged.
• --output and --shard interact: an explicit --output FILE forces
  --shard never (one file as asked); --output DIR shards into
  DIR/map/ under the usual rules.
• The MAP.md Contents index is quieter: files with no symbols, doc,
  or parse error collapse into a per-directory also present: line
  instead of empty sections; test files move into a collapsed
  <details>tests (N files)</details> block; and the redundant
  (parse error) marker is dropped (the Overview's parse-error list
  already carries it).

[0.8.0] — 2026-06-13

Added

• The generated MAP.md now opens with a one-line note steering agents
  to dekko summary and the query/context/affected commands (or
  the MCP tools) instead of reading the whole file.
• An optional PostToolUse hook snippet in the README keeps the map
  refreshed as you edit, made cheap by the freshness fast path below.
• Symbol-anchored notes — durable, committed annotations keyed by
  symbol id. dekko note add <symbol> "<text>", note list [<symbol>]
  (with --orphaned to find notes whose symbol moved), and
  note rm <symbol> [INDEX]. Notes live in .dekko/notes.json and are
  shown inline by dekko query symbol and dekko context (toggle with
  --notes/--no-notes, default on). Exposed over MCP as add_note and
  list_notes (14 tools total). The plugin ships a dekko-notes skill
  telling Claude Code to consult notes before editing, write them after
  non-obvious changes, and re-anchor them after a rename.
• dekko summary — a ~40-line repo digest meant to be read whole:
  file/symbol/edge counts, language mix, a per-directory rollup (file
  and symbol counts, internal vs cross-directory coupling, and a
  purpose line from the directory's index/module docstring), the
  load-bearing (fan-in) and orchestrating (fan-out) symbols, likely
  entry points, and parse errors. --json and --no-tests like the
  other read commands. The /map plugin command now prints this digest
  instead of a raw byte count, and points the agent at the query
  surface rather than the full .dekko/MAP.md.
• The MCP server now serves resources: resources/list /
  resources/read expose dekko://summary, and a matching summary
  tool covers clients that only call tools (12 tools total).
• dekko affected [REV] — the test files a runner should exercise
  after a change. Combines two kinds of evidence: reverse call-graph
  reachability from every added/changed symbol (direct at one hop,
  transitive beyond), plus an always-on import-edge fallback
  (import) that catches tests touching changed files through
  fixtures, references, or deleted symbols where no call edge
  survives. Prints a ready-to-paste pytest … line; --json,
  --limit; exit 0 none / 1 impacted / 2 bad rev. Exposed over
  MCP as the impacted_tests tool (the server now has 11 tools).
  Static analysis can't see fixture injection or dynamic dispatch, so
  the report is a set of strong leads, not a proof of completeness.
• Context packs (v2): the target and every neighbor now carry their
  doc first line; new strictly-opt-in --with-source inlines the
  target's body plus the exact call-site lines (> line: code) of
  hop-1 callers. Source counts against --budget and is truncated
  from the bottom (with a marker) after neighbors are trimmed — the
  target's signature and location always survive. The MCP
  get_context_pack tool accepts a matching with_source flag.
  JSON output gains doc on symbols, sites on neighbors, and
  source/source_truncated when source is requested.
• dekko query callers|callees X --sites — one row per call site
  (path:line of each call expression) instead of one per related
  definition. The MCP get_callers/get_callees tools accept a
  matching sites flag.
• dekko query uses NAME — list every symbol that references an
  external (out-of-repo) name such as Path or run, with call
  sites; exposed over MCP as the new find_usages tool (the server
  now has 10 tools).
• --no-tests on query, context, trace, unused, and stats —
  excludes test files' symbols and edges from results entirely (a
  bare-name query that collided with a test fixture now resolves).
• Text output of query and context ends with a (~N tokens)
  self-metering footer (never present with --json).
• map.json doc version 3 (older documents still load, with
  defaults for the new fields):
  • Call edges carry lines — the sorted, deduplicated 1-based lines
    of every call site backing the edge. External calls do too.
  • Symbols carry doc — the first line of the symbol's docstring or
    doc comment, extracted best-effort per language (Python
    docstrings; //////! for Rust; // blocks for Go; /** */
    and // for JS/TS/Java/C/C++; preceding comments for Tier-2
    grammars). Files carry a module-level doc the same way.
  • Symbols carry test — whether the defining file is test code
    (path-based: test directories and filename patterns).
• New classify module hosting the shared test-path classifier
  (moved from unused, which now imports it).

Changed

• Freshness checks are faster on large repos: provenance records an
  (mtime, size) signature per file, and a file whose signature is
  unchanged is no longer re-hashed. The content hash still decides for
  any file whose stat moved, so verdicts are unchanged; maps written
  before this release fall back to hashing every file.
• External calls in map.json always name their caller: module-level
  calls use the path::<module> convention instead of null, and
  every entry records its call-site lines.
• The .dekko/ directory now governs its own ignores via an inner
  .gitignore (*, !.gitignore, !notes.json) and dekko no longer
  adds a blanket .dekko/ entry to the repository .gitignore —
  generated maps and the cache stay ignored, while notes.json is
  trackable. (A repo whose .gitignore already excludes .dekko/ from
  an earlier version must drop that line for notes to be committable.)