Commit 44a52f05 authored by Jan Reimes's avatar Jan Reimes
Browse files

docs: update documentation structure and guidelines for clarity 

- Revise documentation levels for better modularity and clarity.
- Update AGENTS.md to reflect core guidelines for coding agents.
- Enhance index.md with a clear entry point for documentation.
- Modify misc.md to correct environment variable names for consistency.
parent 95573882

AGENTS.md

+15 −6
Original line number Diff line number Diff line
@@ -239,16 +239,25 @@ Whenever you execute shell commands (including via `just`, `uv`, `pytest`, or an 


### User Documentation



The project maintains three levels of documentation:

The project maintains a modular documentation structure:



1. **README.md** - Project overview, installation, basic usage

1. **docs/QUICK_REFERENCE.md** - Comprehensive command reference (MUST be kept current)

1. **docs/history/** - Chronological changelog of all significant changes

1. **README.md** - Project overview, installation, and Quick Start examples.

1. **docs/index.md** - Main documentation entry point (Jekyll-ready).

1. **docs/QUICK_REFERENCE.md** - Comprehensive command reference (MUST be kept current).

1. **docs/*.md** - Modular task-oriented guides (crawl, query, utils, etc.).

1. **docs/history/** - Chronological changelog of all significant changes.



**Critical Rules:**



- `docs/QUICK_REFERENCE.md` **MUST** always be up to date and reflect the current state of ALL commands

- When adding or modifying commands, **BOTH** the history file AND `docs/QUICK_REFERENCE.md` must be updated

- `docs/QUICK_REFERENCE.md` and related modular files **MUST** always be up to date and reflect the current state of ALL commands.

- When adding or modifying commands, **BOTH** the history file AND the relevant documentation files must be updated.



## Data Source Guidelines



- **WhatTheSpec (whatthespec.net)** is the primary unauthenticated community source for metadata.

- **3GPP Portal (EOL)** is the official authenticated fallback source.

- Credentials (EOL) are only needed for authoritative 3GPP-official data or when WhatTheSpec is unavailable.

- For most users, **WhatTheSpec** is sufficient and preferred as it requires no login.



## AGENTS.md File Design Guidelines

docs/agents-md/800_Documentation.md

+6 −5
Original line number Diff line number Diff line
@@ -28,16 +28,17 @@ 


This repository maintains separate documentation for humans and for coding agents:



1. **docs/QUICK_REFERENCE.md** - Human-facing CLI usage and behavior (examples, flags)

1. **docs/index.md** - Main documentation entry point (Jekyll-ready)

1. **docs/*.md** - Modular task-oriented user guides (crawl, query, utils, etc.)

1. **README.md** - Project overview and contributor entry points

1. **docs/agents-md/** - Agent-facing modular implementation and workflow guidance

1. **AGENTS.md** - Table of contents for all agent-facing modular documentation

1. **AGENTS.md** - Core guidelines and rules for coding agents (standalone context)



### Critical Rules



- **AGENTS.md** serves as the central table of contents for all development documentation

- Modular files in `docs/agents-md/` contain specific aspects of development guidelines

- When adding or modifying features, update relevant sections in the appropriate modular files

- The modular user documentation in `docs/` **MUST** always be up to date and reflect current CLI behavior

- **AGENTS.md** serves as the primary rule set and context for AI assistants

- When adding or modifying features, update relevant sections in both user docs (`docs/*.md`) and agent docs (`docs/agents-md/`)

- Keep documentation consistent with actual implementation



### Documentation Workflow

docs/misc.md

+3 −3
Original line number Diff line number Diff line
@@ -38,11 +38,11 @@ While `tdoc-crawler` primarily uses **WhatTheSpec** for its speed and lack of re 


### Resolution Order



The tool prefers unauthenticated community access first, falling back to the 3GPP portal if credentials are provided:

The tool prefers unauthenticated community access first, falling back to 3GPP portal if credentials are provided:



1. CLI parameters (`--eol-username`, `--eol-password`).

2. Environment variables (`EOL_USERNAME`, `EOL_PASSWORD`).

3. Interactive prompt (if `EOL_PROMPT=true`).

2. Environment variables (`TDC_EOL_USERNAME`, `TDC_EOL_PASSWORD`).

3. Interactive prompt (if `TDC_EOL_PROMPT=true`).



## Directory Structure