Re-split the docs by role and rewrite STATUS.md as a design delta #46

New issue

Open

opened 2026-11-13 10:09:45 +01:00 by omp-deck · 0 comments

omp-deck commented

2026-11-13 10:09:45 +01:00

Collaborator

Problem

docs/STATUS.md is badly stale. It was last touched in 686e082 ("build(assets):
manage Bulma with bun and lint the frontend in CI"), before all the VictoriaLogs and
view work landed, and it now asserts things that are flatly false:

"There is no VictoriaLogs integration of any kind — no HTTP client dependency, no
LogsQL construction, no log model", while src/victorialogs/{mod,client,entry,stream}.rs
exists with VictoriaLogs::new, search, LogEntry, parse_line, parse_labels, and
reqwest/url/jiff/tokio-util/thiserror are all in Cargo.toml.
"src/views/ — the view trait and all views. Nothing resembling a view exists", while
src/views/{mod,all}.rs exists (LogRow, ViewState, all::{QUERY, LIMIT, load}).
"templates/views/, templates/partials/log_row.html" absent — both exist, as does
templates/error.html.
"VICTORIALOGS_URL and VICTORIALOGS_TOKEN do not exist" — both are clap/env options
in src/main.rs, the URL required, the token hidden from help behind a Secret
newtype whose Debug prints [redacted].
"wiremock — not a dev-dependency; nothing fakes an upstream" — it is a
dev-dependency, and tests/common/upstream.rs wraps it in a FakeUpstream replay
harness fed by tests/fixtures/*.jsonl.
"Error handling … Plain-text responses only" — AppError renders
templates/error.html as HTML; only /api/health and the render-failure fallback are
plain text.
Tests listed as web.rs, assets.rs, api/core.rs, omitting tests/views.rs (12
tests) and tests/victorialogs.rs (7).
JavaScript listed as index.js plus livereload.js, omitting tz.js,
view-state.js and view-all.js.
"No commit-message convention is established (history is a single Initial commit)" —
the history is conventional commits throughout and docs/development.md documents the
convention.

The deeper cause is that the four documentation files do not hold to distinct roles, so
the same material is written down more than once and the copies drift. The intended
division is:

docs/DESIGN.md — the full design: the vision and the big-picture decisions that keep
work inside it. Not a catalogue of every implementation detail; detail intrinsic to an
obvious requirement (rendering timestamps in the reader's timezone, for instance) needs
no design entry.
AGENTS.md — how an agent is supposed to work in this repository.
docs/STATUS.md — only what differs from the wanted design.
docs/development.md — local setup, commands, layout, and the conventions a human
contributor needs.

Against that, AGENTS.md currently carries a large amount of design (its "Architecture &
Data Flow" section and its six "Invariants", each of which already has a corresponding
DESIGN.md decision), and duplicates docs/development.md's command and layout tables.

Plan

Documentation only. No file under src/, templates/, tests/ or assets/ is touched,
and no behaviour changes, so the build and the test suite are unaffected at every step.

Four stale doc comments were found during planning and are deliberately left alone:
src/views/mod.rs:1 ("each owns a LogsQL base query, its parameters and its template" —
no view owns parameters, and the templates are declared in src/routes/web/mod.rs),
src/views/mod.rs:20-21 ("the eventual SSE path"), src/views/all.rs:3-4 ("filters grow
here"), and src/views/all.rs:12-13 ("the detail view that will read it"). Do not edit
them.

Step 1 — Move architecture and invariants into `docs/DESIGN.md`

docs/DESIGN.md is today an intro paragraph followed by 15 numbered decisions, each with
rationale and rejected alternatives. Insert two new unnumbered sections between the
intro paragraph and ## 1. Purpose: a curated reader, not an explorer, in this order,
leaving the existing numbering untouched:

## Architecture, carrying across from AGENTS.md (lines 21–64) the content of
"The view abstraction", "Dependency direction" (including the
routes -> views -> victorialogs code block and the "Strictly one-way" rule) and
"Request flow" (both the search-view and tail-view flow blocks). Keep the existing
### subheadings as ### under the new ##. Move the prose as written; adjust only
what is needed for it to read as design rather than instruction.
## Invariants, carrying across all six invariants from AGENTS.md lines 65–83 as a
single numbered list, preserving their order and wording. Replace the current lead-in
("These are the rules most easily got wrong. See docs/DESIGN.md for why.") with a
lead-in stating that these are the rules derived from the decisions below and the ones
most easily got wrong, and append to each invariant a pointer to the decision it
derives from:
- 1 (views emit base queries only) → §11, §3
- 2 (the search path always sends limit) → §11
- 3 (one copy of row markup) → §6
- 4 (the server is stateless) → §2
- 5 (never render upstream errors through |safe) → §7
- 6 (internal view links carry the time range) → §12

Then repair two references inside docs/DESIGN.md:

The intro, lines 4–5: "Rules derived from these decisions live in
AGENTS.md; what is actually built lives in STATUS.md."
Rewrite so it states that the derived rules are the Invariants section below, and that
STATUS.md records where the tree differs from this design.
§11, line 179: "which is why this is stated as an invariant in AGENTS.md" → point at
the Invariants section of this file instead.

Step 2 — Strip `AGENTS.md` to agent-facing material

Delete from AGENTS.md:

The whole ## Architecture & Data Flow section (lines 21–83, including its four ###
subsections, up to but not including ## Key Directories), now living in
docs/DESIGN.md.
The whole ## Key Directories section (lines 84–101, including the trailing "Adding a
view is a four-step operation" sentence). docs/development.md §Layout already carries
both the path table and that sentence.
The whole ## Development Commands section (lines 102–159), except the three pieces
docs/development.md does not already carry, which move to docs/development.md
§Commands in Step 3: the cargo-watch scoping rationale, the docker build -t logview .
release-image invocation, and the description of the CI job graph.

Keep ## Project Overview, ## Code Conventions & Common Patterns, ## Important Files,
## Runtime/Tooling Preferences and ## Testing & QA, stripping the design prose that
now lives in docs/DESIGN.md and replacing it with a link:

## Project Overview: keep the first sentence identifying what logview is. Replace
the "It is not a general LogsQL explorer…" paragraph with one sentence plus a link
to docs/DESIGN.md §1.
## Code Conventions & Common Patterns: keep router composition, the per-method handler
module pattern, template-struct placement, the AppError/bail! rules, the
testability seam, the async rule, formatting, and the crate-layout quirk. In the error
policy list, replace the rationale for surfacing upstream errors verbatim with a
pointer to invariant 5 in docs/DESIGN.md; keep the operative rules themselves (HTML
errors on browser routes, plain text on /api/health, and the mid-stream SSE rule that
an event: error is emitted because the 200 is already committed).
## Important Files: keep the table as-is.
## Runtime/Tooling Preferences: keep the configuration table (LOGVIEW_ADDR,
VICTORIALOGS_URL, VICTORIALOGS_TOKEN, RUST_LOG) and the secret-handling rule
(redacted in Debug, set once as a default Authorization header, never per-call,
never logged), and keep the rule that templates resolve asset URLs through
crate::assets::url. Replace with links to docs/DESIGN.md: the prefix-denotes-
ownership rationale (§13), the asset-pipeline rationale including why Sass is not a
build.rs and why both profiles hash (§14), the Bulma/dart-sass choice (§15), and the
two-independent-auth-paths note (§4a).
## Testing & QA: keep as-is.

Finally, update the preamble pointers at AGENTS.md lines 3–7 to describe the new
division: docs/DESIGN.md is the full design including the architecture and the
invariants; docs/STATUS.md is where the tree differs from that design; docs/development.md
is setup, commands, layout and commit conventions. Keep the existing warning that the
design describes the target, not the current tree, and that STATUS.md must be consulted
before assuming a module exists.

Step 3 — Absorb the three unique command notes into `docs/development.md`

Add to docs/development.md §Commands:

After the just dev edit/result table, the cargo-watch scoping rationale from
AGENTS.md: the watcher is scoped to src, templates and Cargo.toml on purpose,
because watching the whole tree would restart the server whenever Sass writes
gen/assets/, downgrading every style save into a full page reload.
The release-image invocation docker build -t logview ., noting that it is the only
path that exercises embedded assets, which debug builds do not.
A short description of the CI job graph attached to the existing sentence about CI
spelling its steps out: .forgejo/workflows/pr.yaml builds gen/assets once in an
assets job and hands it to check (clippy -D warnings + fmt --check) and test
as an artifact; a lint job runs stylelint and Biome independently; an image job
builds the release image and smoke-tests the running container over HTTP.

Also fix the docs/ row of the §Layout table (line 76), which currently reads
"STATUS.md (what exists)": it now records where the tree differs from the design.

Leave §Planning and §Git commits in this file untouched.

Step 4 — Rewrite `docs/STATUS.md` as a design delta

Replace the file in full. One entry per gap, each naming the DESIGN.md section it
deviates from and the current partial state where one exists. No file paths, no symbol
names, no "what exists" inventory. Final content:

# Implementation Status

What differs between the tree and the design in [`DESIGN.md`](DESIGN.md).

Only deviations are listed. Anything not mentioned here either matches the design or is
implementation detail the design deliberately does not cover. This file is expected to
churn and to shrink to nothing.

## Gaps

- **No tail mode** (§5, §6, §11). Nothing streams log data. The upstream client offers a
  single buffered search, no view declares a mode, and there is no SSE route for rows.
  The only SSE in the tree is the debug-only asset-reload channel.
- **No time range** (§12). No view accepts a range, nothing is parsed from the URL, and
  internal links carry nothing forward. Queries are unbounded and rely on the result
  limit alone.
- **No view abstraction** (§3). There is no view trait and no registry. The one view is a
  plain module with a fixed query and a hardcoded route, and its template type is
  declared in the route layer rather than owned by the view.
- **One curated view** (§1). The dashboard offers a single unfiltered view over all logs;
  the remaining cards are disabled placeholders.
- **The search transport applies `limit` only** (§11, invariant 2). `sort_direction` is
  never sent. Ordering is whatever the upstream returns, reversed at render time.
- **No toolchain pin.** Edition 2024 implies a minimum compiler that nothing enforces; CI
  uses whatever stable it resolves. Deliberately deferred.

Step 5 — Repair `README.md`

README.md line 32 describes AGENTS.md as "architecture, conventions, and development
commands" and line 34 describes docs/STATUS.md as "what is actually implemented". Both
are wrong after Steps 2 and 4. Rewrite the three documentation bullets so AGENTS.md is
how an agent works in this repository, docs/DESIGN.md is the design including the
architecture and invariants, and docs/STATUS.md is where the tree differs from the
design. Add a bullet for docs/development.md (setup, commands, layout, commit
conventions), which the list currently omits.

Verification

Working directory: the repository root. No build is required — nothing outside docs/,
AGENTS.md and README.md is edited — but the Rust suite must still be green, since a
template or source file touched by accident would show up there.

No duplicated design content. Each of these must match in exactly one file:
- grep -rn "routes -> views -> victorialogs" AGENTS.md docs/ README.md → only
  docs/DESIGN.md (docs/development.md keeps its own one-line prose form
  "Dependencies run one way: routes -> views -> victorialogs", which is not this
  block and must survive).
- grep -rn "Invariants" AGENTS.md docs/ → the heading appears only in
  docs/DESIGN.md; occurrences in AGENTS.md are references, not a list.
- grep -rn "Architecture & Data Flow\|## Key Directories\|## Development Commands" AGENTS.md
  → no matches.
No dangling cross-references. grep -rn "AGENTS.md" docs/ README.md and
grep -rn "STATUS.md\|DESIGN.md\|development.md" AGENTS.md README.md docs/ — every
hit must describe the new division. In particular docs/DESIGN.md must no longer say
rules derived from these decisions live in AGENTS.md, and §11 must no longer say an
invariant is stated in AGENTS.md.
Every STATUS.md gap is true of the tree. Each claim, checked against the source:
- no tail: grep -rn "fn tail\|logsql/tail" src/ → no matches; the only SSE route
  outside src/dev_reload.rs must be none (grep -rn "Sse\|text/event-stream" src/
  hits src/dev_reload.rs only).
- no time range: grep -rni "time_range\|from=\|until=\|_time:" src/views/ src/routes/
  → no matches.
- no view trait: grep -rn "trait View\|enum Mode" src/ → no matches.
- no sort_direction: grep -rn "sort_direction" src/ → no matches.
- no toolchain pin: test -f rust-toolchain.toml → false.
  If any of these now returns a match, the corresponding bullet is wrong and must be
  dropped or narrowed rather than published as written.
STATUS.md no longer makes any of the stale claims. grep -rniE "wiremock|no VictoriaLogs integration|Initial commit|plain-text responses only" docs/STATUS.md
→ no matches.
Nothing outside the four documentation files changed. git status --short lists at
most AGENTS.md, README.md, docs/DESIGN.md, docs/STATUS.md,
docs/development.md.
Suite still green. just test passes (it builds assets first; a bare cargo test
compiles against whatever is already in gen/assets/).

Assumptions & contingencies

The Architecture and Invariants sections go before ## 1. Purpose in
docs/DESIGN.md, unnumbered, so the existing decision numbers stay stable and nothing
that cites a §number breaks. If a reviewer prefers them numbered as §16/§17 at the end,
that is a pure relocation of the same text.
docs/development.md is assumed to remain the single home of the command and layout
tables; AGENTS.md links to it rather than restating it. An agent reading only
AGENTS.md will therefore need one hop to find just recipes — accepted, because two
copies are what caused the current drift.
Intrinsic implementation detail gets no DESIGN.md section and no STATUS.md entry:
the view preference cookie, server-side timezone rendering, the wrap toggle, the HTML
error template, and Renovate. If a reviewer wants any of them documented, it is an
addition to docs/DESIGN.md, not a gap in docs/STATUS.md.

## Problem `docs/STATUS.md` is badly stale. It was last touched in `686e082` ("build(assets): manage Bulma with bun and lint the frontend in CI"), before all the VictoriaLogs and view work landed, and it now asserts things that are flatly false: - "There is **no VictoriaLogs integration of any kind** — no HTTP client dependency, no LogsQL construction, no log model", while `src/victorialogs/{mod,client,entry,stream}.rs` exists with `VictoriaLogs::new`, `search`, `LogEntry`, `parse_line`, `parse_labels`, and `reqwest`/`url`/`jiff`/`tokio-util`/`thiserror` are all in `Cargo.toml`. - "`src/views/` — the view trait and all views. Nothing resembling a view exists", while `src/views/{mod,all}.rs` exists (`LogRow`, `ViewState`, `all::{QUERY, LIMIT, load}`). - "`templates/views/`, `templates/partials/log_row.html`" absent — both exist, as does `templates/error.html`. - "`VICTORIALOGS_URL` and `VICTORIALOGS_TOKEN` do not exist" — both are clap/env options in `src/main.rs`, the URL required, the token hidden from help behind a `Secret` newtype whose `Debug` prints `[redacted]`. - "`wiremock` — not a dev-dependency; nothing fakes an upstream" — it is a dev-dependency, and `tests/common/upstream.rs` wraps it in a `FakeUpstream` replay harness fed by `tests/fixtures/*.jsonl`. - "Error handling … Plain-text responses only" — `AppError` renders `templates/error.html` as HTML; only `/api/health` and the render-failure fallback are plain text. - Tests listed as `web.rs`, `assets.rs`, `api/core.rs`, omitting `tests/views.rs` (12 tests) and `tests/victorialogs.rs` (7). - JavaScript listed as `index.js` plus `livereload.js`, omitting `tz.js`, `view-state.js` and `view-all.js`. - "No commit-message convention is established (history is a single `Initial commit`)" — the history is conventional commits throughout and `docs/development.md` documents the convention. The deeper cause is that the four documentation files do not hold to distinct roles, so the same material is written down more than once and the copies drift. The intended division is: - `docs/DESIGN.md` — the full design: the vision and the big-picture decisions that keep work inside it. Not a catalogue of every implementation detail; detail intrinsic to an obvious requirement (rendering timestamps in the reader's timezone, for instance) needs no design entry. - `AGENTS.md` — how an agent is supposed to work in this repository. - `docs/STATUS.md` — only what differs from the wanted design. - `docs/development.md` — local setup, commands, layout, and the conventions a human contributor needs. Against that, `AGENTS.md` currently carries a large amount of design (its "Architecture & Data Flow" section and its six "Invariants", each of which already has a corresponding `DESIGN.md` decision), and duplicates `docs/development.md`'s command and layout tables. ## Plan Documentation only. No file under `src/`, `templates/`, `tests/` or `assets/` is touched, and no behaviour changes, so the build and the test suite are unaffected at every step. Four stale doc comments were found during planning and are **deliberately left alone**: `src/views/mod.rs:1` ("each owns a LogsQL base query, its parameters and its template" — no view owns parameters, and the templates are declared in `src/routes/web/mod.rs`), `src/views/mod.rs:20-21` ("the eventual SSE path"), `src/views/all.rs:3-4` ("filters grow here"), and `src/views/all.rs:12-13` ("the detail view that will read it"). Do not edit them. ### Step 1 — Move architecture and invariants into `docs/DESIGN.md` `docs/DESIGN.md` is today an intro paragraph followed by 15 numbered decisions, each with rationale and rejected alternatives. Insert two new **unnumbered** sections between the intro paragraph and `## 1. Purpose: a curated reader, not an explorer`, in this order, leaving the existing numbering untouched: 1. `## Architecture`, carrying across from `AGENTS.md` (lines 21–64) the content of "The view abstraction", "Dependency direction" (including the `routes -> views -> victorialogs` code block and the "Strictly one-way" rule) and "Request flow" (both the search-view and tail-view flow blocks). Keep the existing `###` subheadings as `###` under the new `##`. Move the prose as written; adjust only what is needed for it to read as design rather than instruction. 2. `## Invariants`, carrying across all six invariants from `AGENTS.md` lines 65–83 as a single numbered list, preserving their order and wording. Replace the current lead-in ("These are the rules most easily got wrong. See `docs/DESIGN.md` for why.") with a lead-in stating that these are the rules derived from the decisions below and the ones most easily got wrong, and append to each invariant a pointer to the decision it derives from: - 1 (views emit base queries only) → §11, §3 - 2 (the search path always sends `limit`) → §11 - 3 (one copy of row markup) → §6 - 4 (the server is stateless) → §2 - 5 (never render upstream errors through `|safe`) → §7 - 6 (internal view links carry the time range) → §12 Then repair two references inside `docs/DESIGN.md`: - The intro, lines 4–5: "Rules derived from these decisions live in [`AGENTS.md`](../AGENTS.md); what is actually built lives in [`STATUS.md`](STATUS.md)." Rewrite so it states that the derived rules are the Invariants section below, and that `STATUS.md` records where the tree differs from this design. - §11, line 179: "which is why this is stated as an invariant in `AGENTS.md`" → point at the Invariants section of this file instead. ### Step 2 — Strip `AGENTS.md` to agent-facing material Delete from `AGENTS.md`: - The whole `## Architecture & Data Flow` section (lines 21–83, including its four `###` subsections, up to but not including `## Key Directories`), now living in `docs/DESIGN.md`. - The whole `## Key Directories` section (lines 84–101, including the trailing "Adding a view is a four-step operation" sentence). `docs/development.md` §Layout already carries both the path table and that sentence. - The whole `## Development Commands` section (lines 102–159), except the three pieces `docs/development.md` does **not** already carry, which move to `docs/development.md` §Commands in Step 3: the `cargo-watch` scoping rationale, the `docker build -t logview .` release-image invocation, and the description of the CI job graph. Keep `## Project Overview`, `## Code Conventions & Common Patterns`, `## Important Files`, `## Runtime/Tooling Preferences` and `## Testing & QA`, stripping the design prose that now lives in `docs/DESIGN.md` and replacing it with a link: - `## Project Overview`: keep the first sentence identifying what `logview` is. Replace the "It is **not** a general LogsQL explorer…" paragraph with one sentence plus a link to `docs/DESIGN.md` §1. - `## Code Conventions & Common Patterns`: keep router composition, the per-method handler module pattern, template-struct placement, the `AppError`/`bail!` rules, the testability seam, the async rule, formatting, and the crate-layout quirk. In the error policy list, replace the rationale for surfacing upstream errors verbatim with a pointer to invariant 5 in `docs/DESIGN.md`; keep the operative rules themselves (HTML errors on browser routes, plain text on `/api/health`, and the mid-stream SSE rule that an `event: error` is emitted because the 200 is already committed). - `## Important Files`: keep the table as-is. - `## Runtime/Tooling Preferences`: keep the configuration table (`LOGVIEW_ADDR`, `VICTORIALOGS_URL`, `VICTORIALOGS_TOKEN`, `RUST_LOG`) and the secret-handling rule (redacted in `Debug`, set once as a default `Authorization` header, never per-call, never logged), and keep the rule that templates resolve asset URLs through `crate::assets::url`. Replace with links to `docs/DESIGN.md`: the prefix-denotes- ownership rationale (§13), the asset-pipeline rationale including why Sass is not a `build.rs` and why both profiles hash (§14), the Bulma/dart-sass choice (§15), and the two-independent-auth-paths note (§4a). - `## Testing & QA`: keep as-is. Finally, update the preamble pointers at `AGENTS.md` lines 3–7 to describe the new division: `docs/DESIGN.md` is the full design including the architecture and the invariants; `docs/STATUS.md` is where the tree differs from that design; `docs/development.md` is setup, commands, layout and commit conventions. Keep the existing warning that the design describes the target, not the current tree, and that `STATUS.md` must be consulted before assuming a module exists. ### Step 3 — Absorb the three unique command notes into `docs/development.md` Add to `docs/development.md` §Commands: - After the `just dev` edit/result table, the `cargo-watch` scoping rationale from `AGENTS.md`: the watcher is scoped to `src`, `templates` and `Cargo.toml` on purpose, because watching the whole tree would restart the server whenever Sass writes `gen/assets/`, downgrading every style save into a full page reload. - The release-image invocation `docker build -t logview .`, noting that it is the only path that exercises embedded assets, which debug builds do not. - A short description of the CI job graph attached to the existing sentence about CI spelling its steps out: `.forgejo/workflows/pr.yaml` builds `gen/assets` once in an `assets` job and hands it to `check` (clippy `-D warnings` + `fmt --check`) and `test` as an artifact; a `lint` job runs stylelint and Biome independently; an `image` job builds the release image and smoke-tests the running container over HTTP. Also fix the `docs/` row of the §Layout table (line 76), which currently reads "`STATUS.md` (what exists)": it now records where the tree differs from the design. Leave §Planning and §Git commits in this file untouched. ### Step 4 — Rewrite `docs/STATUS.md` as a design delta Replace the file in full. One entry per gap, each naming the `DESIGN.md` section it deviates from and the current partial state where one exists. No file paths, no symbol names, no "what exists" inventory. Final content: ```markdown # Implementation Status What differs between the tree and the design in [`DESIGN.md`](DESIGN.md). Only deviations are listed. Anything not mentioned here either matches the design or is implementation detail the design deliberately does not cover. This file is expected to churn and to shrink to nothing. ## Gaps - **No tail mode** (§5, §6, §11). Nothing streams log data. The upstream client offers a single buffered search, no view declares a mode, and there is no SSE route for rows. The only SSE in the tree is the debug-only asset-reload channel. - **No time range** (§12). No view accepts a range, nothing is parsed from the URL, and internal links carry nothing forward. Queries are unbounded and rely on the result limit alone. - **No view abstraction** (§3). There is no view trait and no registry. The one view is a plain module with a fixed query and a hardcoded route, and its template type is declared in the route layer rather than owned by the view. - **One curated view** (§1). The dashboard offers a single unfiltered view over all logs; the remaining cards are disabled placeholders. - **The search transport applies `limit` only** (§11, invariant 2). `sort_direction` is never sent. Ordering is whatever the upstream returns, reversed at render time. - **No toolchain pin.** Edition 2024 implies a minimum compiler that nothing enforces; CI uses whatever stable it resolves. Deliberately deferred. ``` ### Step 5 — Repair `README.md` `README.md` line 32 describes `AGENTS.md` as "architecture, conventions, and development commands" and line 34 describes `docs/STATUS.md` as "what is actually implemented". Both are wrong after Steps 2 and 4. Rewrite the three documentation bullets so `AGENTS.md` is how an agent works in this repository, `docs/DESIGN.md` is the design including the architecture and invariants, and `docs/STATUS.md` is where the tree differs from the design. Add a bullet for `docs/development.md` (setup, commands, layout, commit conventions), which the list currently omits. ## Verification Working directory: the repository root. No build is required — nothing outside `docs/`, `AGENTS.md` and `README.md` is edited — but the Rust suite must still be green, since a template or source file touched by accident would show up there. 1. **No duplicated design content.** Each of these must match in exactly one file: - `grep -rn "routes -> views -> victorialogs" AGENTS.md docs/ README.md` → only `docs/DESIGN.md` (`docs/development.md` keeps its own one-line prose form "Dependencies run one way: `routes -> views -> victorialogs`", which is not this block and must survive). - `grep -rn "Invariants" AGENTS.md docs/` → the heading appears only in `docs/DESIGN.md`; occurrences in `AGENTS.md` are references, not a list. - `grep -rn "Architecture & Data Flow\|## Key Directories\|## Development Commands" AGENTS.md` → no matches. 2. **No dangling cross-references.** `grep -rn "AGENTS.md" docs/ README.md` and `grep -rn "STATUS.md\|DESIGN.md\|development.md" AGENTS.md README.md docs/` — every hit must describe the new division. In particular `docs/DESIGN.md` must no longer say rules derived from these decisions live in `AGENTS.md`, and §11 must no longer say an invariant is stated in `AGENTS.md`. 3. **Every STATUS.md gap is true of the tree.** Each claim, checked against the source: - no tail: `grep -rn "fn tail\|logsql/tail" src/` → no matches; the only SSE route outside `src/dev_reload.rs` must be none (`grep -rn "Sse\|text/event-stream" src/` hits `src/dev_reload.rs` only). - no time range: `grep -rni "time_range\|from=\|until=\|_time:" src/views/ src/routes/` → no matches. - no view trait: `grep -rn "trait View\|enum Mode" src/` → no matches. - no `sort_direction`: `grep -rn "sort_direction" src/` → no matches. - no toolchain pin: `test -f rust-toolchain.toml` → false. If any of these now returns a match, the corresponding bullet is wrong and must be dropped or narrowed rather than published as written. 4. **STATUS.md no longer makes any of the stale claims.** `grep -rniE "wiremock|no VictoriaLogs integration|Initial commit|plain-text responses only" docs/STATUS.md` → no matches. 5. **Nothing outside the four documentation files changed.** `git status --short` lists at most `AGENTS.md`, `README.md`, `docs/DESIGN.md`, `docs/STATUS.md`, `docs/development.md`. 6. **Suite still green.** `just test` passes (it builds assets first; a bare `cargo test` compiles against whatever is already in `gen/assets/`). ## Assumptions & contingencies - The `Architecture` and `Invariants` sections go **before** `## 1. Purpose` in `docs/DESIGN.md`, unnumbered, so the existing decision numbers stay stable and nothing that cites a §number breaks. If a reviewer prefers them numbered as §16/§17 at the end, that is a pure relocation of the same text. - `docs/development.md` is assumed to remain the single home of the command and layout tables; `AGENTS.md` links to it rather than restating it. An agent reading only `AGENTS.md` will therefore need one hop to find `just` recipes — accepted, because two copies are what caused the current drift. - Intrinsic implementation detail gets no `DESIGN.md` section and no `STATUS.md` entry: the `view` preference cookie, server-side timezone rendering, the wrap toggle, the HTML error template, and Renovate. If a reviewer wants any of them documented, it is an addition to `docs/DESIGN.md`, not a gap in `docs/STATUS.md`.