# eriic-builds/fieldnotes architecture

> Architecture diagram of the GitHub repository eriic-builds/fieldnotes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eriic-builds/fieldnotes
- Repository: https://github.com/eriic-builds/fieldnotes
- Video tour (about a minute): https://gitdiagram.com/eriic-builds/fieldnotes/video

## Overview

Fieldnotes is a documentation-authoring framework for producing source-backed Markdown collections that AI agents can discover and use. The main workflow is to research a subject, organize and author focused pages, then expose the collection through the generated llms.txt index and a searchable website. The README also describes validation and publishing, but those are maintenance and deployment support rather than core authoring stages. Wiring beyond the documented workflow is not inferred from the sampled sources.

Main entry points: [`docs`](https://github.com/eriic-builds/fieldnotes/tree/main/docs) (Markdown corpus), [`scripts/build_llms.py`](https://github.com/eriic-builds/fieldnotes/blob/main/scripts/build_llms.py) (Index generator), [`docs/topics`](https://github.com/eriic-builds/fieldnotes/tree/main/docs/topics) (Topic collection), [`mkdocs.yml`](https://github.com/eriic-builds/fieldnotes/blob/main/mkdocs.yml) (Searchable site)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guidance["Authoring guidance"]
  node_instructions["Agent instructions<br/>[AGENTS.md]"]
  node_research["Research workflow"]
  node_authoring["Authoring guide<br/>[authoring.md]"]
  node_maintenance["Maintenance guide<br/>[maintenance.md]"]
end

subgraph group_content["Documentation content"]
  node_starters["Starter pages"]
  node_collection["Topic collection"]
  node_markdown["Markdown corpus"]
end

subgraph group_discovery["Discovery and browsing"]
  node_generator["Index generator<br/>[build_llms.py]"]
  node_index["Agent index<br/>[llms.txt]"]
  node_site["Searchable site<br/>[mkdocs.yml]"]
end

node_agent(("Authoring agent"))

node_agent -->|"follows"| node_instructions
node_agent -->|"researches with"| node_research
node_agent -->|"authors with"| node_authoring
node_agent -->|"adapts"| node_starters
node_agent -->|"creates"| node_collection
node_collection -->|"stores pages"| node_markdown
node_generator -->|"reads pages"| node_markdown
node_generator -->|"generates"| node_index
node_site -->|"renders"| node_markdown

click node_instructions "https://github.com/eriic-builds/fieldnotes/blob/main/AGENTS.md"
click node_research "https://github.com/eriic-builds/fieldnotes/blob/main/docs/guides/research-workflow.md"
click node_authoring "https://github.com/eriic-builds/fieldnotes/blob/main/docs/guides/authoring.md"
click node_maintenance "https://github.com/eriic-builds/fieldnotes/blob/main/docs/guides/maintenance.md"
click node_starters "https://github.com/eriic-builds/fieldnotes/tree/main/docs/starter-pages"
click node_collection "https://github.com/eriic-builds/fieldnotes/tree/main/docs/topics"
click node_markdown "https://github.com/eriic-builds/fieldnotes/tree/main/docs"
click node_generator "https://github.com/eriic-builds/fieldnotes/blob/main/scripts/build_llms.py"
click node_index "https://github.com/eriic-builds/fieldnotes/blob/main/llms.txt"
click node_site "https://github.com/eriic-builds/fieldnotes/blob/main/mkdocs.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_instructions,node_research,node_authoring,node_maintenance toneBlue
class node_starters,node_collection,node_markdown toneAmber
class node_generator,node_index,node_site toneMint
class node_agent toneIndigo
```

## Components

### Authoring guidance

- [Agent instructions](https://github.com/eriic-builds/fieldnotes/blob/main/AGENTS.md): `AGENTS.md`
- [Research workflow](https://github.com/eriic-builds/fieldnotes/blob/main/docs/guides/research-workflow.md): `docs/guides/research-workflow.md`
- [Authoring guide](https://github.com/eriic-builds/fieldnotes/blob/main/docs/guides/authoring.md): `docs/guides/authoring.md`
- [Maintenance guide](https://github.com/eriic-builds/fieldnotes/blob/main/docs/guides/maintenance.md): `docs/guides/maintenance.md`

### Documentation content

- [Starter pages](https://github.com/eriic-builds/fieldnotes/tree/main/docs/starter-pages): `docs/starter-pages`
- [Topic collection](https://github.com/eriic-builds/fieldnotes/tree/main/docs/topics): `docs/topics`
- [Markdown corpus](https://github.com/eriic-builds/fieldnotes/tree/main/docs): `docs`

### Discovery and browsing

- [Index generator](https://github.com/eriic-builds/fieldnotes/blob/main/scripts/build_llms.py): `scripts/build_llms.py`
- [Agent index](https://github.com/eriic-builds/fieldnotes/blob/main/llms.txt): `llms.txt`
- [Searchable site](https://github.com/eriic-builds/fieldnotes/blob/main/mkdocs.yml): `mkdocs.yml`

### Other components

- **Authoring agent**

## Connections

- Authoring agent → Agent instructions: follows
- Authoring agent → Research workflow: researches with
- Authoring agent → Authoring guide: authors with
- Authoring agent → Starter pages: adapts
- Authoring agent → Topic collection: creates
- Topic collection → Markdown corpus: stores pages
- Index generator → Markdown corpus: reads pages
- Index generator → Agent index: generates
- Searchable site → Markdown corpus: renders