kompend 2026.10.4__tar.gz

kompend-2026.10.4/.agents/CHECKS.md

@@ -0,0 +1,94 @@
+# AGENTS.md — Checks
+
+Verification commands, enforcement scripts, and new-code checklist.
+
+## General Checks
+
+### Pattern: New Code Checklist
+
+Before writing a function, tick these. If you can't, stop and fix the foundation
+first — the alternatives are all antipatterns:
+
+- **Limit values** — from config/DEFAULTS/field, not a literal slice?
+- **Enum values** — from StrEnum members, not bare strings?
+- **Imports** — at module level, not inside function bodies?
+- **Global state** — no `global` keyword or module-level mutable singletons?
+- **Noqa suppressions** — actually necessary, with a justification comment?
+
+### Pattern: Enforcement Scripts
+
+A small set of scripts catch what linting misses: bare-string contract keys,
+magic-number crops, banned-noqa patterns. Run them locally before pushing.
+All exit non-zero on violations; `mise run check-all` runs them (no CI job
+does — see **Wiring** below).
+
+Two guarantees keep them honest: a scan that finds no files is an error (an
+empty scan is not a pass), and an enforced contract that no longer exists in
+the code (moved module, renamed enum) fails the script instead of warning.
+Per-line waivers exist for sites the rule cannot judge — `# nocheck: <reason>`
+in field-consistency, `# noqa: <code>` in antipatterns. The reason is part of
+the waiver: it states why this site is legitimate.
+
+### Extension
+
+| Who | When | What |
+|-----|------|------|
+| Project maintainer | Adding a new verification tool | Verification section |
+| Project maintainer | Adding a new enforcement script | Enforcement table |
+| Project maintainer | Adding a new checklist item | Checklist |
+
+---
+
+## Project-specific Checks — kompend
+
+### Verification
+
+- Run `ruff check` on changed Python files before committing
+- Run `uv run pytest tests/unit -x --timeout=30` for unit test coverage
+- Run `uv run pytest tests/integration -x --timeout=30` for integration tests (no real-engine calls — must be fast)
+- Run `ty check src/kompend` for type checking (mypy is not used)
+- Run `uv run python scripts/checks/check_field_consistency.py` to catch hard-coded contract keys
+- Run `uv run python scripts/checks/check_antipatterns.py` to catch banned-noqa, magic crops, `try/except ImportError` guards, and `global` keyword usage
+- Verify `kompend.toml.example` stays in sync with `DEFAULTS` when adding config keys
+- After changing `src/kompend/core/paths.py`, verify no hard-coded path strings
+  exist in other `.py` files
+- After changing CLI commands, MCP tools, config keys, or output format, check
+  `skills/kompend/SKILL.md` for stale or missing info
+- Run `uv run mkdocs build --strict` when changing documentation files
+
+### New Code Checklist
+
+Tick these BEFORE writing a function:
+
+- **Limit value** — from `config.get(...)` / `DEFAULTS` / `PipelineConfig` field?
+  Literals like `[:10]` silently drop data. Use `DisplayConfig` for display
+  limits or `BudgetConfig` for LLM input/output budgets.
+- **Role / task / compiler / tier** — from `LLMRole` / `AgentTask` / `Compiler` /
+  `Tier` enum? Bare strings like `role="compile.extract"` will be rejected.
+- **Import** — at module level? Function-body imports (`PLC0415`) are rejected
+  except for `try/except ImportError` probes for explicitly optional deps.
+- **Global state** — no `global` keyword or module-level mutable singleton
+  (`_cache = {}`, `_instance = None`). A genuinely process-wide switch (one-shot
+  setup guard, verbosity toggle) may use `global` with a justified
+  `# noqa: PLW0603` — a contextvar would be wrong for it.
+- **Noqa suppression** — actually necessary with a justification comment?
+  `PLC0415` and other banned-noqa rules cannot be suppressed.
+
+### Enforcement scripts
+
+| Script | Catches | Lives in |
+|---|---|---|
+| `ruff check` | Most lint issues (PLC0415/E402 are warnings, not errors) | ruff.toml |
+| `scripts/checks/check_field_consistency.py` | Bare-string contract keys | scripts/checks/ |
+| `scripts/checks/check_antipatterns.py` | Banned-noqa, magic crops, `try/except ImportError` guards, `global` | scripts/checks/ |
+| `scripts/checks/check_dox.py` | DOX file size budgets, cross-file duplication | scripts/checks/ |
+| `scripts/analyze/analyze_codebase.py` | Files/submodules exceeding net-line targets (>350 lines/file, >7 files/submodule) | scripts/analyze/ |
+
+**Wiring.** Git honours one `core.hooksPath`; this repo points it at
+`.githooks` (`mise run install-hooks`). `.githooks/pre-commit` runs the
+forbidden ruff rules plus the three gates, then `_delegate.sh` forwards to the
+hook files other tools own in `.beads/hooks` (beads, repowise) — never edit
+those, the tools regenerate them. `check_dox.py`'s scope is the DOX files plus
+the core `.agents/` state files; `.agents/skills/**` and `.agents/history/**` are
+not project DOX and are skipped. No CI job runs these; `mise run check-all` runs
+the two AST gates.

kompend-2026.10.4/.agents/CODE.md

@@ -0,0 +1,79 @@
+# AGENTS.md — Code
+
+kompend code policies: antipatterns, boundaries, error handling. Load when writing
+or reviewing code — production or tests.
+
+## Python style
+
+Follow the `python-ultimate` skill when in doubt about Python style, structure,
+or conventions — it takes precedence over a conflicting habit or default.
+
+## Antipatterns
+
+| Pattern | Verdict | Fix |
+|---|---|---|
+| Hard-coded model name (`model="ollama/llama3.2"`) | ❌ | Config field default, never a function signature |
+| Domain value as function default (`prompt_budget: int = 200_000`) | ❌ | Config dataclass field |
+| `x: T | None = None` with hidden default in body | ❌ | Config field; docstring if `None` is truly meaningful |
+| `content[:200]` / `text[:4096]` | ❌ | Full content, or a batch size derived from config/model |
+| Config fallback duplicating a runtime provider value (`dim = 384`) | ❌ | Read it from the provider at runtime (`provider.dim`) |
+| Bare schema/field-name literals (`hit.get("source_file")`) | ❌ | `StrEnum` / `Final[str]` symbol imported at every site |
+| Hard-coded `"KOMP_*"` env-var literal (`os.environ.get("KOMP_WIKI_DIR")`, `envvar=`) | ❌ | `EnvVar` member from `kompend.core.env` |
+| Stable-shape dict without a schema (JSONL records, persisted entries — lint history, dedup store, graph edges, citations) | ❌ | `TypedDict` next to the owning model — types keys at zero runtime cost. Dataclasses only where the shape is also constructed/validated in code |
+| Absolute path in a `.kompend/` artifact (`citing_source = str(path)`) | ❌ | Relativize at the persistence boundary (`rel_to_vault(path, base_dir)`) |
+
+The first five are instances of the universal magic-number rule
+(see `POLICIES.md`); rows 6–9 are kompend-specific. Two of them are enforced:
+`scripts/checks/check_field_consistency.py` (bare contract keys) and
+`scripts/checks/check_antipatterns.py` (env-var literals, magic crops). Run both
+before committing — see `CHECKS.md`.
+
+## Boundaries
+
+- **Every behaviour-affecting value is a config field** in a `_KompendBaseModel`
+  (`LLMConfig`, `BudgetConfig`, …) with a `Field(validation_alias=...)`. This
+  holds even when the default equals the current literal: the field is the
+  single source of truth, and `DEFAULTS` is generated from the schema.
+- **No absolute paths in `.kompend/` artifacts.** Paths in every persisted record
+  (provenance, references, assets, dedup, memory, search index, compile state,
+  wiki cache) are vault-relative and POSIX-normalized. In-memory `Path` objects
+  may be absolute; relativization happens at the persistence boundary.
+- **No `from typing import TYPE_CHECKING`** and no `if TYPE_CHECKING:` blocks —
+  they diverge runtime from the type checker. Break import cycles structurally
+  (neutral module, Protocol, or a runtime-only import at its call site) and use
+  `from __future__ import annotations` for forward references.
+- **Never suppress** `PLC0415` (inline imports), `ANN001`/`ANN202` (missing
+  annotations) — hard errors, no `# noqa`. For non-ruff scanner false positives
+  (vibecheck, sloppylint, aislop) use that tool's own directive, so each
+  suppression names the scanner it targets.
+- **Heavy optional dependencies stay lazy** (parsecraft, torch, transformers,
+  datasketch, scipy, crawl4ai, pydantic-ai, MCP SDK, zvec) so CLI startup stays
+  fast. Package level: `lazy.attach(__name__, submod_attrs={...})`. Function
+  level: the registry factory (`get_backend()`), never a module-scope import.
+  Canonical pattern: `src/kompend/preprocessing/parsers/__init__.py`.
+- **Temp files** go in `./tmp` (gitignored) or `tempfile.TemporaryDirectory()`.
+
+## Error handling — prefer "let it burn"
+
+Propagate. `None` may mean a thing is **absent** (lookup miss, optional value
+unset), never that an operation **failed** — returning `None` for a corrupt file
+is the antipattern, and it pushes `if x is None` chains onto every caller.
+
+The only valid `try/except` sites:
+
+1. **Trust boundary** — translate a low-level error into a user-facing message
+   at the CLI/MCP top level; catch narrowly, report the real cause.
+2. **Optional-feature probe** — narrow to the specific exception
+   (`ImportError`, `FileNotFoundError`), never `Exception`.
+3. **Best-effort enrichment** — per-item catch that *records* the failure
+   (SKIP result, warning log) and continues the batch.
+4. **Cache miss** — narrow to `(json.JSONDecodeError, OSError)` and log at
+   `WARNING` so corruption stays visible.
+
+Forbidden: `except Exception: pass`, `except Exception: return None`,
+`# noqa: BLE001`/`S110` to silence a bare except, and catching a corrupt
+internal-state file (wiki cache, tier state, compile state) to reset it —
+corruption is a bug; raise.
+
+Removing a `try/except` that surfaces a real error to someone who needs it is
+the correct fix.

kompend-2026.10.4/.agents/FILES.md

@@ -0,0 +1,98 @@
+# AGENTS.md — Files
+
+Path constants, VaultPaths, and naming conventions. Load when touching files.
+
+## General Files
+
+### Pattern: Single Source of Truth for Paths
+
+Project artifact paths should be defined in a single constants module. No other
+module hard-codes directory or file names. Always import from the constants
+module.
+
+### Pattern: Resolved Path Object
+
+Use a path-resolver class that takes a base directory and exposes every artifact
+path as a property. This ensures consistent path construction across the codebase.
+
+### Extension
+
+| Who | When | What |
+|-----|------|------|
+| Project maintainer | Adding a new artifact file/directory | Add constant row |
+| Project maintainer | Renaming an artifact | Update constant value |
+| Project maintainer | Changing the paths module | Update module reference |
+
+---
+
+## Project-specific Files — kompend
+
+### Path Constants — Single Source of Truth
+
+All on-disk artifact names are `Final[str]` constants in **`src/kompend/core/paths.py`**.
+
+**Rule:** `".kompend"`, `"cache"`, `"config.toml"`, `"vectors"`, `"memory.db"`,
+`"last_wiki.json"`, etc. must **never** appear as a literal in
+any `.py` file outside `paths.py`. Always import from `kompend.core.paths`.
+
+| Constant | Value | Usage |
+|----------|-------|-------|
+| `KOMP_DIR` | `".kompend"` | Root metadata directory |
+| `KOMP_DB_FILE` | `"kompend.db"` | Single non-vector SQLite store (`.kompend/kompend.db`) |
+| `CACHE_SUBDIR` | `"cache"` | Cache component within `KOMP_DIR` |
+| `CACHE_DIR` | `".kompend/cache"` | Full relative cache path (for DEFAULTS) |
+| `CONFIG_FILE` | `"config.toml"` | Project-local config |
+| `VECTORS_DIR` | `"vectors"` | Embedding vector store |
+| `VECTORS_MANIFEST_FILE` | `"vectors.manifest.json"` | Vector id sidecar (legacy — now the `vector_manifest` row) |
+| `DOWNLOADED_FILE` | `"downloaded.json"` | URL download manifest (legacy — now `downloaded` table) |
+| `MEMORY_DB_FILE` | `"memory.db"` | Semantic query-memory collection **directory** (zvec, not SQLite) |
+| `MEMORY_LOG_FILE` | `"memory.jsonl"` | Memory append-only log (legacy — now `memory_log` table) |
+| `MEMORY_STORE_FILE` | `"memory.json"` | Memory state export (legacy — now `memory_states` table) |
+| `PROVENANCE_DIR` | `"provenance"` | Provenance trace directory (legacy — now `provenance` table) |
+| `SUMMARIES_SUBDIR` | `"summaries"` | Per-source summary pages (`wiki/summaries/`) |
+| `EXPORTED_DIR_NAME` | `"exported"` | Full-source markdown exports (top-level, on demand) |
+| `QUALITY_FILE` | `"quality.md"` | Verification summary page (`wiki/quality.md`) |
+| `VERIFICATION_FILE` | `"verification.json"` | Verification results |
+| `PRIVATE_FILE` | `"private.json"` | Private page manifest |
+| `COMPILE_STATE_FILE` | `"compile_state.json"` | Tier state checkpoint |
+| `LINT_HISTORY_FILE` | `"lint_history.jsonl"` | Append-only lint history log |
+| `STATE_FILE` | `"state.json"` | General state file |
+
+**Configurable directory names** (`"sources"`, `"wiki"`) live in `DEFAULTS`
+under `["paths"]["sources_dir"]` and `["paths"]["output_dir"]` — not in
+`paths.py`, because users can override them.
+
+### Project root naming
+
+The project root directory is always called `base_dir`. Never use `target_dir`,
+`resolved_base`, `project_root`, or `sources_dir.parent`.
+
+### VaultPaths
+
+`VaultPaths` (in `paths.py`) resolves concrete paths inside a vault:
+
+```python
+from kompend.core.paths import VaultPaths
+
+paths = VaultPaths(base_dir)
+paths.cache_dir  # base_dir/.kompend/cache
+paths.compile_state_file  # base_dir/.kompend/compile_state.json
+paths.wiki_cache_file  # base_dir/.kompend/last_wiki.json
+paths.extract_dir  # base_dir/.kompend/cache/extract (legacy — now extract cache layer in kompend.db)
+paths.images_dir  # base_dir/.kompend/cache/images
+```
+
+| Context | Pattern |
+|---------|---------|
+| Module has `config: PipelineConfig` | `config.paths.cache_dir` |
+| Module has `base_dir: Path` | `VaultPaths(base_dir).cache_dir` |
+| Module has `output_dir: Path` | `VaultPaths(output_dir.parent).cache_dir` |
+| Test with `tmp_path` | `VaultPaths(tmp_path).cache_dir` |
+
+### Test conventions
+
+- All tests use `pytest` and `tmp_path` for filesystem operations.
+- Unit tests must mock external dependencies (LLM, network, filesystem).
+- Integration tests calling LLM APIs must use `@pytest.mark.skipif` checking
+  for API key availability.
+- Test files follow `test_<module>.py` naming.

kompend-2026.10.4/.agents/HISTORY.md

@@ -0,0 +1,95 @@
+# AGENTS.md — History
+
+Past design decisions, known issues, and "why we banned X." Optional background
+reading; not required for day-to-day work.
+
+## General History
+
+### Pattern: Design Decision Log
+
+Record significant decisions that shaped the codebase. Each entry explains the
+context, the decision, and where it landed. This prevents future contributors
+from re-litigating settled questions.
+
+### Rules
+
+- **Newest first**, **one entry per decision**, 2–6 lines: context, decision,
+  commit. Detail belongs in `.agents/history/` — link it.
+- **Budgeted like every `.agents/` file (≤120 lines).** Over budget → archive the
+  oldest entries to `.agents/history/`, leaving a pointer line.
+- Move resolved entries to a "Resolved" subsection rather than deleting them.
+
+### Extension
+
+| Who | When | What |
+|-----|------|------|
+| Any contributor | Making a notable design decision | Add entry at top |
+| Project maintainer | Resolving a known violation | Move to Resolved subsection |
+| Project maintainer | Deprecating a tool/pattern | Add rationale entry |
+
+---
+
+## Project-specific History — kompend
+
+### Archived plans — full detail in `.agents/history/`
+
+| Archived | Slug | What landed |
+| -------- | ---- | ----------- |
+| 2026-09-16 | `context-window-provider-overrides` | `[providers.<name>].context_window` now beats auto-discovery (step 1 of `discover_context_window`); `kompend doctor` stops reporting override-only blocks of *known* providers as `missing base_url` while still erroring on unknown ids |
+| 2026-09-24 | `kompend-0iv2-audit` | Read-only audit resolving a tracker-vs-code contradiction from the code; the reusable part is the method — dynamic-access sweep plus `git log -S "<Class>"` |
+| 2026-09-24 | `kompend-storage-migration` | `.kompend/` consolidated into one SQLite file (`core/store/`); clean cut, no migration code — `61147c5f`, `f6aee4c0`, `8aaf2eca` |
+| 2026-08-22 | `markdown-only-vault` | The wiki is represented by its generated markdown alone; `.kompend/` is purely derived — `5d493119`, `51ea1111` |
+| 2026-08-16 | `source-export-md`, `category-extraction`, `rumdl-format-wiring` | `kompend sources export` from the parse cache; configurable extraction categories; rumdl wiring for every markdown writer |
+| 2026-08-15 | `env-any-refactor`, `rlm-integration` | Typed config access replacing `Any`; the optional RLM code-exploration capability |
+| 2026-08-14 | `migration-plan`, `refactoring-plan` | `summarization-pydantic-ai` context management (`edb4d49`); super-module splits into `stages/`, `engine/`, `tools/`, `flows/`, `pages/` |
+
+### Why text-in-code is banned
+
+Prompts embedded in Python were undiscoverable, unversionable, and invisible to
+non-developers. All prompt text now lives in Jinja2 templates or pack TOML. The
+remaining legacy violations are tracked in beads — `bd list`, not a table here.
+
+### Why litellm was removed
+
+`c8055c0`. After moving to pydantic-ai's native `infer_model()` plus the
+models.dev catalog, litellm was 40+ transitive dependencies and added latency
+around a unified `build_model()` path. Removed.
+
+### Why heavy imports are lazy-loaded (SPEC-0001)
+
+`kompend --help` took ~80s because `register_all_commands()` imported every command
+module, each transitively pulling docling/torch/pydantic-ai/MCP. `lazy.attach()`
+in five package `__init__.py` files, plus the `get_backend()` factory for
+function-body-only classes, took it to 11s (−86%). No `_LAZY` dicts, no
+`__getattr__` fallbacks.
+
+### Why `compile.embedding.dim` was removed
+
+The `dim = 384` fallback shaped only the empty-text dedup vector while non-empty
+fingerprints used `provider.embed()`'s real dimension, so a mismatch crashed
+`EmbeddingMatcher.score(..., strict=True)` — and `make_provider()` ignored the
+hint anyway. Both zvec stores had the same literal; all are gone and dim always
+resolves from `provider.dim`, lazily probed. Stores rebuild when the stored
+dimension differs from the current model's.
+
+### Why `_ENV_LIST_VARS` is schema-derived
+
+The hand-listed `KOMP_*` names drifted from the schema (splitting a `str` field
+into a list, listing a dead var). It now derives from list-typed config-map
+fields. Separately, `KOMP_CHARS_PER_TOKEN` was a dead env var — the real alias is
+`KOMP_LLM_DEFAULT_CHARS_PER_TOKEN` and the value already flows via
+`default_chars_per_token`.
+
+### Lint remediation collapsed to page generation (2026-08-14)
+
+Three overlapping tiers became one: LLM-generate missing concept pages from
+cached extractions. Image-embed fixing moved into `run --fix` as the
+`image-embed` structural rule; recommendations live only in `kompend lint gaps`;
+`RemediationAction.tier` was removed. Same change added the `rumdl` structural
+rule (`rumdl check` JSON over the vault's markdown, sources never touched, files
+passed explicitly to bypass rumdl's ignore filtering).
+
+### Release versioning
+
+Calver `YYYY.M.D` / `YYYY.M.D.N` — no zero-padding, no `v` prefix. See
+`.forgejo/workflows/release.yml`.

kompend-2026.10.4/.agents/MAINTENANCE.md

@@ -0,0 +1,67 @@
+# AGENTS.md — Maintenance
+
+How to keep `.agents/` files current.
+
+## General Maintenance
+
+### Process
+
+1. When a rule changes, update the file that owns it — never another file.
+2. When adding a new `.agents/` file, add it to the `.agents/ index` table
+   in root `AGENTS.md`.
+3. After any `.agents/` change, check the AGENTS.md index for stale entries.
+
+### Principles
+
+- **Single source of truth.** Each rule lives in exactly one file.
+  Cross-reference with a one-liner, never duplicate.
+- **AGENTS.md is an index.** It points to `.agents/` files; it does not contain
+  the rules themselves.
+- **No tree figures.** ASCII directory trees rot immediately. Regenerate on
+  demand: `rg --files | tree-cli --fromfile`.
+
+### Extension
+
+| Who | When | What |
+|-----|------|------|
+| Project maintainer | Adding a new `.agents/` file | Add to AGENTS.md index |
+| Project maintainer | Renaming a `.agents/` file | Update AGENTS.md + cross-references |
+| Any contributor | Finding stale references | Fix or report |
+
+---
+
+## Project-specific Maintenance — kompend
+
+### File update triggers
+
+| File | Update when |
+|------|-------------|
+| `POLICIES.md` | Adding/changing priorities, boundaries, DOX authoring, response format |
+| `CODE.md` | Adding/changing a code antipattern, boundary, or the error-handling policy |
+| `FILES.md` | Renaming/adding path constants in `paths.py` |
+| `CHECKS.md` | Adding/changing verification commands or checklist items |
+| `HISTORY.md` | Resolving a known violation or making a notable design decision |
+| `ONBOARDING.md` | Project structure or entry points change |
+| `plans/` | New feature implementation starts |
+| `history/` | HISTORY.md overflow or completed plans archived |
+
+### Plan naming and dating
+
+- Active plans in `plans/` keep their working name (no date prefix) but must
+  carry date info in the document (e.g. a `Created: YYYY-MM-DD` line under
+  the title; update a `Status:` line as work progresses).
+- On archiving into `history/`, rename to `YYYY-MM-DD-<plan-slug>.md` where
+  the date is the **completion date** (e.g. `2026-08-14-migration-plan.md`).
+  Update any references to the old filename (HISTORY.md entries, links).
+
+### Cross-reference map
+
+| `.agents/` file | Referenced from |
+|-----------------|-----------------|
+| `POLICIES.md` | Root `AGENTS.md`, all subtree `AGENTS.md` `on entry` headers |
+| `CODE.md` | Root `AGENTS.md`, subtree `AGENTS.md` `on entry` headers, `tests/AGENTS.md` |
+| `FILES.md` | Root `AGENTS.md`, all subtree `AGENTS.md` `on entry` headers |
+| `CHECKS.md` | Root `AGENTS.md`, all subtree `AGENTS.md` `on entry` headers |
+| `HISTORY.md` | `src/kompend/AGENTS.md` (text-in-code violations pointer) |
+| `ONBOARDING.md` | Root `AGENTS.md` (First time? line) |
+| `MAINTENANCE.md` | Root `AGENTS.md` (.agents/ index) |

kompend-2026.10.4/.agents/ONBOARDING.md

@@ -0,0 +1,101 @@
+# AGENTS.md — Onboarding
+
+First 5 minutes to get oriented.
+
+## General Onboarding
+
+This file follows a reusable template. Every project should cover:
+
+1. **What to read first** — the AGENTS.md chain: read root, then subtree
+   files for directories you'll touch.
+2. **Key entry points** — 5-10 files that give the fastest orientation.
+3. **Project structure** — one-line purpose per top-level directory.
+4. **Essential commands** — build, test, lint, typecheck with time estimates.
+5. **Key conventions** — the 5-8 rules you'll break most often if you don't
+   know them.
+6. **Where to dig deeper** — documentation index, issue tracker, child DOX docs.
+
+### Extension
+
+| Who | When | What |
+|-----|------|------|
+| Project maintainer | After major code reorganization | Sections 2-3 |
+| Project maintainer | When build/test tooling changes | Section 4 |
+| Project maintainer | When key conventions change | Section 5 |
+
+**Never duplicate content.** Reference the source file. This document is a map,
+not a rulebook — rules live in `POLICIES.md`, path constants in `FILES.md`,
+verification in `CHECKS.md`.
+
+---
+
+## Project-specific Onboarding — kompend
+
+### 1. What is kompend?
+
+kompend = Knowledge Organizer for eXtended documents. A parser-agnostic,
+structure-preserving, LLM-aware knowledge base compiler. 5-tier pipeline:
+Preprocessing → Chunking → Resolution → Compilation → Output.
+
+Every LLM call routes through PydanticAI agents in `src/kompend/agents/`.
+
+### 2. Key entry points (read these first)
+
+| File | Why |
+|------|-----|
+| `AGENTS.md` | Root rail — index to all `.agents/` files |
+| `.agents/POLICIES.md` | Priorities, boundaries, DOX authoring, response format |
+| `.agents/CODE.md` | Code antipatterns, boundaries, error handling |
+| `.agents/FILES.md` | Path constants, VaultPaths, naming |
+| `src/kompend/AGENTS.md` | Python-specific: text-in-code, antipatterns |
+| `docs/index.md` | User-facing documentation index |
+| `kompend.toml.example` | All config keys with comments |
+| `src/kompend/core/paths.py` | Single source of truth for artifact paths |
+| `src/kompend/core/config/generate.py` | `DEFAULTS` dict — all config defaults |
+
+### 3. Project structure
+
+| Path | Purpose |
+|------|---------|
+| `src/kompend/core/` | Foundation: config, models, paths, pipeline, cache, templates |
+| `src/kompend/agents/` | PydanticAI agents for every LLM call |
+| `src/kompend/llm/` | LLM client, provider registration, failover |
+| `src/kompend/cli/` | Typer-based CLI (thin shell over core) |
+| `src/kompend/preprocessing/` | Parsers (parsecraft adapter, marker, mineru, web) |
+| `src/kompend/compilation/` | Tier 4: extraction, generation, WiCER, output |
+| `src/kompend/search/` | Hybrid search: FTS + vector + RRF |
+| `src/kompend/memory/` | Memory lifecycle: working → episodic → semantic → procedural |
+| `tests/` | Unit, integration, benchmarks |
+| `docs/` | MkDocs user-facing documentation |
+| `.agents/skills/` | Installed agent skills |
+
+### 4. Essential commands
+
+```bash
+uv run pytest tests/unit -x --timeout=30          # unit tests
+uv run pytest tests/unit -q --no-cov --tb=line     # unit tests (compact)
+uv run pytest tests/integration -x --timeout=120   # integration tests
+uv run pytest tests/benchmarks/ -q --no-cov        # benchmarks
+ruff check                                           # lint
+ty check src/kompend                                    # type check (not mypy)
+uv run python scripts/checks/check_field_consistency.py     # bare-string contract keys
+uv run python scripts/checks/check_antipatterns.py          # banned-noqa, magic crops, global
+uv run mkdocs build --strict                        # doc build check
+```
+
+### 5. Key conventions
+
+- **`uv run`** for everything — never `python`, `python3`, `pip`
+- **`base_dir`** — canonical name for the project root directory
+- **`paths.py`** — all artifact names live here; never hard-code `.kompend`, `cache`, etc.
+- **`VaultPaths`** — resolve concrete paths with `VaultPaths(base_dir)`
+- **StrEnum** — roles, tasks, compilers, tiers must use enum members, not bare strings
+- **No tree figures** in AGENTS.md — regenerate: `rg --files | tree-cli --fromfile`
+- **No cross-level duplication** in DOX chain — reference, never copy
+
+### 6. Where to dig deeper
+
+- Each `src/kompend/` subdirectory has its own `AGENTS.md` (DOX child doc)
+- `docs/index.md` — full documentation index
+- `.agents/HISTORY.md` — past design decisions, known issues
+- `bd` (beads) — issue tracking: `bd list`, `bd show <id>`

kompend-2026.10.4/.agents/POLICIES.md

@@ -0,0 +1,120 @@
+# AGENTS.md — POLICIES
+
+Always applicable. Priorities, boundaries, DOX authoring, response format.
+
+## Priorities
+
+Correctness · Evidence · Safety · Minimal changes · Consistency · Performance
+
+## Boundaries
+
+- NEVER fabricate paths, commits, APIs, config keys, env vars, test results, or
+  benchmark numbers. If you don't know, say so.
+- NEVER guess at command names, flags, or paths — read source or run `--help`.
+- NEVER add secrets, API keys, or tokens to files; use env vars.
+- NEVER run destructive commands (`rm -rf`, `git reset --hard`,
+  `git push --force`) without explicit confirmation.
+- NEVER delete or move files without explicit instruction.
+- NEVER modify `.gitignore`, `pyproject.toml`, `ruff.toml`, or CI config, and add
+  no new dependency, without explicit instruction.
+- NEVER create temp files outside `tmp/` (gitignored) — never `_tmp_*.py` at the root.
+
+## Change constraints
+
+- Minimal, surgical edits. Preserve existing style. No unrelated refactoring.
+- When changing tests, update only directly affected tests.
+
+## Code quality
+
+Universal defaults. kompend code policies — antipatterns, boundaries, error
+handling — live in `CODE.md`; project-specific standards in child AGENTS.md.
+
+- **SRP** — one reason to change per module/function. If a name needs "and",
+  split it. Remove dead branches, unreachable conditions, and unused params or
+  imports before finishing.
+- **DRY** — check for an existing helper/constant before adding one; extract on
+  the _third_ occurrence (Rule of Three), not earlier.
+- Prefer a little duplication over the wrong premature abstraction; add no new
+  code-quality tooling, patterns, or value-object rules by default.
+
+## Completion checklist
+
+Change solves the stated problem · relevant validation ran (or gaps explicitly
+stated, see `CHECKS.md`) · no unintended side effects · no secrets added
+
+## DOX authoring (keep AGENTS.md lean)
+
+AGENTS.md and `.agents/` files share limited context. Bloat and duplication are
+the failure mode — they waste context on every subtree entry and drift apart as
+rules change.
+
+### Where a rule lives
+
+Ask: **what is the highest (most general) tier that fully applies?** Put the rule
+there and nowhere else.
+
+- All code in the project → `.agents/POLICIES.md` (universal) or `CODE.md` (code
+  policies). This is the default; when unsure, here.
+- Only inside one subtree (framework-specific template rules) → that subtree's
+  `AGENTS.md`.
+- Only navigation → the parent's Child DOX Index, nothing else.
+
+### Reference, don't restate
+
+A rule appears in **exactly one file**; every other file touching it uses a
+**pointer line** — `<topic> — see <file>`. Never copy the rule, its rationale, or
+its example into a second file.
+
+### Rule first, rationale second, never third
+
+A DOX line is the rule. If a rationale is costly to rediscover, add one short
+clause. Never multi-paragraph explanations or more than one ❌/✅ pair per rule —
+those belong in a skill or a `docs/` page, linked once.
+
+### Content rules
+
+- **No tree views** — generate on demand: `rg --files | tree-cli --fromfile`.
+- **No history** — git log has it; record only decisions costly to rediscover,
+  in `HISTORY.md` with commit refs.
+- **No TODO lists or trackers** — use beads (`bd`).
+- **Long-form explanation** belongs in `docs/` or a skill: link it, don't inline.
+
+### Size budget
+
+- `.agents/` files: ≤ **120 lines** (always-injected context).
+- Subtree `AGENTS.md`: ≤ **250 lines** (loaded cumulatively with every parent on
+  entry — deep-path cost adds up).
+
+Over budget means the doc restates instead of pointing, or hoards rationale. Cut
+first; split the subtree only as a last resort.
+
+## Response format
+
+Concise and specific. No filler, intros, or restated requirements. Answer direct
+questions directly. For review/debugging/analysis: findings with references,
+conclusion, approach, and caveats.
+
+## Project-specific Policies — kompend
+
+### Implementation plans
+
+- Plans go in `.agents/plans/<feature>/` — gitignored, never committed. Mutable
+  working artifacts, not shipped docs. Prefix filenames with phase numbers so
+  file order matches implementation order; carry `Created:` and `Status:` lines.
+  Shipped docs (user-facing guides, API references) go in `docs/` and ARE
+  committed.
+
+### Documentation and archiving
+
+- `HISTORY.md` over budget → archive older entries to `.agents/history/` with a
+  one-line pointer left behind. `.agents/history/` IS version-controlled; it
+  holds the durable decision records.
+- Completed plans move to `.agents/history/` as `YYYY-MM-DD-<slug>.md`
+  (completion date), with references updated. See `MAINTENANCE.md`.
+
+### User Preferences
+
+- Concise, direct answers with no filler or intros
+- Use `uv run` for all Python execution, never direct `python` calls
+- English-only for code, docs, and commits; conventional commits (`feat:`, `fix:`,
+  `chore:`, `docs:`)