Files

T

Joseph Doherty 32f26272ae Initial commit: Wonderware / System Platform tools and reference

Five tools under one repo, all docs organized per DOCS-GUIDE.md:

- aalogcli: .NET 4.8 / x86 CliFx CLI for reading System Platform binary
  logs (*.aaLGX) for LLM debugging, built on aaOpenSource/aaLog. Commands:
  last, tail, range, unread, fields. Stable JSON envelope under --llm-json.
  Build template under lib/build/ for rebuilding aaLogReader.dll.

- aot: ArchestrA Object Toolkit 2014 v4.0 reference material. Dev guide
  (Markdown converted from CHM), API reference for the ArchestrA.Toolkit
  namespace, and the Monitor / Watchdog VS sample solutions.

- graccesscli: .NET 4.8 / x86 CliFx CLI that automates Galaxy
  configuration via the ArchestrA GRAccess COM interop. Includes session
  daemon, IPC protocol, and llm-json envelope contract.

- grdb: SQL/DDL exploration of the Galaxy Repository database. DDL
  captures, reusable queries, hierarchy / contained-name <-> tag-name
  translation notes.

- histdb: LLM-oriented reference for AVEVA Historian retrieval. INSQL
  linked-server, extension tables, every wwXxx time-domain extension,
  every retrieval mode, alarm/event SQL recipes, REST API. Distilled
  from the 243-page Historian Retrieval Guide.

Root contains:
- CLAUDE.md: thin index pointing into each tool's README.
- DOCS-GUIDE.md: doctrine for organizing docs for LLM consumption.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-03 18:22:20 -04:00

6.8 KiB

Raw Permalink Blame History

DOCS-GUIDE.md

How documentation in this repo is organized and written. The primary consumer of these docs is an LLM coding agent — the rules below are tuned for that, not for human browsing.

Why this matters

LLM agents pay a real cost for every token they read. Documentation that is duplicated, buried, or scattered forces the agent to load more context than the task needs, which slows it down, blows the cache, and lets stale copies drift out of sync. The structure below exists to keep one fact in one place and let the agent reach it through the shortest path.

The three-layer structure

<repo-root>/
  CLAUDE.md           # layer 1: thin index, pointers only
  DOCS-GUIDE.md       # this file
  <tool>/
    README.md         # layer 2: tool entry point, router into deep docs
    CLAUDE.md         # (optional) tool-specific agent guide
    AGENTS.md         # (optional) coding-agent rules for this tool
    <doc-area>/...    # layer 3: deep documentation, one file per concept

Each layer has a strict job. If a piece of content fits two layers, it belongs in the deeper one — only the deeper layer is allowed to grow.

Layer 1 — root `CLAUDE.md`: thin index only

CLAUDE.md answers exactly one question for the agent: "Given this task, which tool's documentation do I open?" Nothing else.

Allowed content:

One paragraph: what this repo is.
A Layout section: each tool folder, one line, with a link to its README.md.
A Tool / resource index table: task → tool, where each cell links into the tool's README.md (or a specific deep doc when that's clearly the right entry point).
Repo-wide conventions and a pointer to this DOCS-GUIDE.md.

Disallowed content:

Tool-specific gotchas, API details, build commands, workflow steps, code samples, schema notes, incident histories.
Any per-doc fan-out (long bulleted lists of every file inside a tool — that belongs in the tool's README.md).
Anything that would have to change when a tool's internals change. Per-tool churn must stay inside the tool folder.

If the agent has to read CLAUDE.md past the index to answer a tool-specific question, CLAUDE.md is too fat. Push the answer down a layer.

Rule of thumb: if CLAUDE.md exceeds ~150 lines or repeats facts that already live inside a tool folder, refactor.

Layer 2 — `<tool>/README.md`: tool entry point

Every top-level folder under the repo root is a "tool" — a discrete bundle of code, reference material, or both. Every tool MUST have a README.md at its own root. That README is a router, not a manual.

Required sections, in this order:

One-sentence identification. What the tool is, what it's for.
Hard constraints / prerequisites. Anything that, if missed, invalidates the rest of the doc — runtime, architecture, auth, admin requirements, vendor installs. Front-load these.
Layout. The folder shape with one-line descriptions of each immediate child. Don't catalog deeply; the agent can ls.
Resource index. Task → file table covering the tool's deep docs and any sibling agent guides (CLAUDE.md, AGENTS.md).
Maintenance. Pointer back to this DOCS-GUIDE.md and to ../CLAUDE.md, with a note that both must be updated when the tool's surface changes.

Disallowed: long prose tutorials, full API references, schema dumps, workflow walkthroughs. The README routes; the deep docs explain.

Layer 3 — deep documentation

Workflow guides, API references, sample projects, incident notes, schema captures. The bulk of the bytes lives here.

Rules:

One file per cohesive concept. Don't merge unrelated topics into a kitchen-sink doc. Don't fragment a single concept across five files because each step felt small.
Lead with a one-sentence summary at the top of every file. Agents grep headers.
Cross-link explicitly with [label](relative/path.md). Bare filenames in prose are invisible to the renderer and to the agent's link-following.
Date and status time-sensitive material (incident notes, regression tracking, "active defect" docs). Stale undated content is worse than no content.
Code samples must be runnable as stated. If a snippet only works under a specific platform constraint, say so inline — don't rely on the reader having read the README first.

Writing conventions

Prefer tables for catalogs (task → resource, type → meaning), numbered lists for ordered procedures, prose for "why".
Don't duplicate content. If the same fact would naturally live in two files, designate one canonical home and have the other link to it. Duplication is the #1 cause of doc drift.
Use relative paths that resolve from the file's own location. Avoid absolute filesystem paths in cross-references.
No decorative chrome. Skip emojis, banner art, "Welcome to..." intros, and trailing summaries that restate the doc.
Be concrete. Name the file, the function, the command, the constraint. Vague guidance ("be careful with COM") wastes tokens.
Mark uncertainty. If something is provisional or unverified, say so. Confident-sounding wrong content is the worst outcome for LLM consumers.

What goes where — quick test

Content	Goes in
"Which tool handles X?"	root `CLAUDE.md` index row
"What is this tool and what constrains it?"	`<tool>/README.md`
"How do I do task X with this tool?"	`<tool>/<doc-area>/<task>.md`
Tool API reference / type catalog	`<tool>/<reference>/...`
Coding rules for an agent working in this tool	`<tool>/AGENTS.md` or `<tool>/CLAUDE.md`
Active incident / regression / defect	`<tool>/<dated-incident>.md`, linked from the tool README
Cross-tool architectural rule	root `CLAUDE.md`, only if it can be violated without entering a tool folder

If you can answer the question by reading only the root CLAUDE.md index plus one <tool>/README.md, the structure is working.

Maintenance discipline

New tool added → create <tool>/README.md first, then add one row to the root CLAUDE.md index pointing to that README. Resist adding a per-file fan-out at the root.
Tool removed → delete the row in CLAUDE.md in the same change. Orphaned index rows are worse than missing ones.
Doc renamed or moved → grep the repo for the old path and fix every reference in the same change. Stale paths are the largest single source of LLM confusion in this repo.
Tool internals change → update the tool's own README and deep docs; touch the root CLAUDE.md only if the task → tool mapping changed.
CLAUDE.md exceeds ~150 lines, or starts repeating tool-internal facts → refactor. Pull content down into the appropriate tool's README.md or deep docs.

When in doubt, ask: would a different tool's agent ever need this? If no, it doesn't belong at the root.

6.8 KiB Raw Permalink Blame History