Publication Boundary
Maintainer-only ledgers and agent procedures are referenced as source material where needed, not republished as public guides.
Current public document
Documentation index
Documentation map, source-of-truth rules, and planned guide boundaries.
Status map
Incomplete guides remain listed as planned placeholders until their source files exist.
This index routes readers to the current documentation set and labels unfinished
guides explicitly. Current operational backlog status lives in docs/PLAN.md.
Completed-slice records live in docs/worklog/. Current system and
component boundaries live in docs/limitations.md.
Source Of Truth
- Code and tests define runtime behavior.
config/*.tomlare sample runtime configs;crates/lm-configdefines parsed config fields and validation.docs/limitations.mdmust describe current unsupported, partial, and operator-dependent behavior.docs/PLAN.mdowns planned work, dependencies, acceptance criteria, and concise completion references.docs/worklog/owns completed-slice commits, verification, review notes, and archived historical records used by generated planning artifacts.scripts/record_worklog.pyis the supported helper for creating or updating worklog records; use it instead of hand-editing JSONL when practical.scripts/install-git-hooksinstalls the tracked pre-commit hook that refreshes duration benchmark and Gantt artifacts for staged planning changes.- Design documents describe target direction unless they explicitly say a behavior is implemented.
Current Docs
| Document | Audience | Status | Use |
|---|---|---|---|
README.md | Everyone | Partial | Project orientation, workspace map, first build, and local demo entry point. |
docs/limitations.md | Users, operators, developers | Current | Explicit and implicit implementation limits by component. |
docs/quickstart.md | First-time users, developers | Current | Verified local demo path from checkout to queryable heartbeat data. |
docs/install.md | Operators, packagers | Current | Manual source-build binary install layout and current unsupported package formats. |
docs/docker.md | Operators, evaluators | Current | Operator-owned container build/run recipe, volumes, ports, token/TLS mounts, and MinIO/S3 wiring. |
docs/PLAN.md | Developers, agents, maintainers | Current | Persistent operational backlog, active slice context, dependencies, and acceptance criteria. |
docs/worklog/ | Developers, agents, maintainers | Current | Per-task structured completed-slice ledger used by Gantt generation and coverage checks. |
docs/worklog/README.md | Developers, agents, maintainers | Current | Worklog file naming and JSONL schema rules. |
scripts/record_worklog.py | Developers, agents, maintainers | Current | Worklog upsert helper that validates task IDs, commit refs, dates, and JSONL shape. |
scripts/git-hooks/pre-commit | Developers, agents, maintainers | Current | Tracked pre-commit hook installed by scripts/install-git-hooks; validates worklog data and refreshes generated planning artifacts when planning inputs are staged. |
docs/user-guide.md | Private console and Grafana users | Current | Console connection, dashboard tabs, fleet overview, live metrics, logs, alerts, Grafana data source setup, query examples, and disabled workflow callouts. |
docs/config.md | Operators, developers | Current | Configuration reference for every collector and agent TOML field, with defaults, validation rules, secret-file behavior, cross-component coupling, and acceptance modes. |
docs/api.md | Integrators, developers | Current | API reference for ingest, Prometheus-compatible query, logs, alerts, live SSE, dashboards, and reconciliation endpoints. |
docs/admin-guide.md | Operators | Current | Deployment topology, auth token management, TLS, spool/queue/cache sizing, object-store modes, identity conflicts, reconciliation, backup/restore, retention, and operational limitations. |
docs/development.md | Contributors, agents | Current | Workspace layout, prerequisites, build/test/lint commands, integration harnesses, planning tools, commit conventions, review gates, and public site build. |
docs/troubleshooting.md | Users, operators | Current | Ingest rejections, auth/TLS failures, queue/spool pressure, object-store failures, partial query warnings, oversized records, identity conflicts, stale live views, config validation, and upgrade procedure. |
docs/design.md | Developers, maintainers | Design reference | Target architecture and rationale; verify against docs/PLAN.md and docs/limitations.md before treating behavior as implemented. |
docs/active-active-s3-ingest.md | Operators, developers | Partial design/reference | S3-manifest ingest direction and active-active constraints; implemented pieces are tracked under object-storage plan items. |
docs/design-artifacts.md | Frontend developers | Reference | Links and notes for design artifacts. |
docs/claude-design-task.md | Frontend developers | Reference | Original console design task context. |
docs/claude-design-public-site-task.md | Frontend developers, maintainers | Reference | Claude Design prompt and intake workflow for public lightmetrics.dev website mockups. |
site/README.md | Frontend developers, maintainers | Current | Static Astro public site package path, build commands, and build-time source boundary. |
docs/gantt.html | Maintainers | Planning artifact | Interactive roadmap viewer that reads docs/gantt-data.js. |
docs/gantt-data.json | Maintainers, tooling | Generated planning artifact | Canonical structured roadmap data generated from plan/worklog data. |
docs/gantt-data.js | Maintainers | Generated browser data wrapper | Same payload as docs/gantt-data.json, wrapped as window.LIGHTMETRICS_GANTT_DATA so docs/gantt.html works from file:// without fetch/CORS handling. |
Planned Guides
These guides are not complete yet. Until each guide exists, the relevant plan row
is the authoritative placeholder and implementation limits remain in
docs/limitations.md.
| Planned path | Plan item | Audience | Status | Scope |
|---|---|---|---|---|
docs/user-guide.md | DOC-02E | Private console and Grafana users | Done | Supported console, Grafana, query, logs, alerts, dashboard, and disabled workflows. |
docs/admin-guide.md | DOC-02F | Operators | Done | Topology, auth, TLS, queue/spool sizing, object-store modes, reconciliation, backup/restore, and retention caveats. |
docs/config.md | DOC-02G | Operators, developers | Done | Every server and agent TOML field, validation rule, default/sample value, secret-file behavior, and cross-component limit coupling. |
docs/api.md | DOC-02H | Integrators, developers | Done | Ingest, query, logs, alerts, live SSE contracts, auth headers, warnings/errors, cursors, limits, and unsupported paths. |
docs/development.md | DOC-02I | Contributors, agents | Done | Workspace layout, codegen, build/test/clippy commands, integration harnesses, UI test boundaries, Gantt generation, review gates, and planning rules. |
docs/troubleshooting.md | DOC-02J | Users, operators | Done | Common ingest, auth/TLS, queue/spool, object-store, query warning, oversized-record, live-view, conflict recovery, config validation, and upgrade procedure. Release notes are included in the same file. |
Maintenance Rule
Any change to runtime behavior, config fields, API shapes, storage layout,
limits, deployment commands, demo scripts, user-visible UI, or operational
process must update the corresponding guide when it exists. If the guide does
not exist yet, update docs/PLAN.md and docs/limitations.md instead of leaving
the documentation gap implicit. Completed slices must also update the matching
docs/worklog/<TASK-ID>.jsonl record so historical evidence does not accumulate
in docs/PLAN.md.