docs: document file naming conventions and clarify structure guidance
Added explicit file-naming rules to page-templates.md so agents know: - Root entry-points: ALL-CAPS (AGENTS.md, README.md) - Containers: <id>-<name>.md (e.g., 101-jellyfin.md) - Infrastructure: lowercase-with-dashes (dns.md, auto-deploy.md) - Plans/investigations: YYYY-MM-DD-slug.md - Skills: lowercase-with-dashes/ folder containing SKILL.md Updated AGENTS.md section 4 (Wiki conventions) to link to page-templates.md and provided quick reference for file naming, page locations, and changelog format. Updated README.md conventions section to mention file naming and link to page-templates.md for the full rules. All agents now have a clear reference chain: 1. AGENTS.md (entry point) → points to conventions 2. page-templates.md (structure) → has file naming + page templates 3. writing-style.md (prose) → has voice, vocabulary, linking rules 4. llm-wiki.md (organization) → has sources/wiki/index/log model Verified: no broken links, all conventions documented, consistency check passes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -4,6 +4,17 @@ The structural templates for each page type. Prose voice, vocabulary, and cross-
|
||||
in [writing-style.md](writing-style.md); the layer model (sources / wiki / index / log) lives in
|
||||
[llm-wiki.md](llm-wiki.md).
|
||||
|
||||
## File naming
|
||||
|
||||
- **Root entry-point files:** ALL-CAPS (e.g. `AGENTS.md`, `README.md`). These are discovery paths — agents and humans find them first.
|
||||
- **Container pages:** `<id>-<name>.md` (e.g. `101-jellyfin.md`, `132-rclone.md`). The `<id>` is the LXC/VM ordinal from `inventory.yaml`.
|
||||
- **Infrastructure / cross-cutting pages:** lowercase-with-dashes (e.g. `dns.md`, `auto-deploy.md`, `mesh.md`). Describes a system, not a specific node.
|
||||
- **Plans / investigations / time-stamped docs:** `YYYY-MM-DD-<slug>.md` (e.g. `2026-07-05-oikos-prometheus-lxc.md`). Date first, then lowercase slug.
|
||||
- **Skills / runbooks:** folder name is lowercase-with-dashes (e.g. `client-enrollment/`), contains `SKILL.md` (uppercase). Emphasizes the skill-name for navigation.
|
||||
- **Indices:** `README.md` or `index.md` (both lowercase). Prefer `README.md` for folders; use `index.md` only when both an intro page and a listing coexist.
|
||||
|
||||
All paths use lowercase letters, numbers, and hyphens (no underscores). This keeps them readable, shell-friendly, and consistent across the repo.
|
||||
|
||||
## Voice
|
||||
|
||||
Concise, technical, sysadmin-to-sysadmin. No marketing prose, no exclamation marks. Full rules in
|
||||
|
||||
Reference in New Issue
Block a user