Skip to content

docs(agents): document the FAQ folder and where a question belongs - #188

Merged
aarora79 merged 1 commit into
mainfrom
docs/agents-faq-convention
Sep 11, 2026
Merged

aarora79 merged 1 commit into
mainfrom
docs/agents-faq-convention

Conversation

@aarora79

Copy link
Copy Markdown
Owner

docs/faq/ landed in #187 but AGENTS.md never mentioned it. An agent reading the canonical guide would not know the folder exists, and would answer the same question somewhere else instead of adding to it.

Three additions, all to AGENTS.md:

  • Repository structure -- the tree now lists docs/faq/ beside docs/release-notes/, with its shape: one file per question plus an index.
  • Documentation conventions -- a new rule for where a question belongs. Write the file in docs/faq/, add a row to the index, phrase the heading as the question a reader types rather than the name the code uses, and do not restate a setup or reference page. Where a fact could sit in both, pick one owner: docs/codex-setup.md owns installing and configuring codex, docs/faq/wiring-codex-to-models.md owns the per-path recipes.
  • Reference-doc list -- a "Questions rather than reference pages" entry pointing at the folder and its first file, and the write-it-down rule at the end of that section now names the FAQ as a destination alongside the model guide and the setup doc.

Every relative link in AGENTS.md resolves (checked programmatically).

After this merges the 0.2.0 tag moves to the new merge commit, so the tag ships the notes plus every doc that describes the release.

docs/faq/ landed in #187 but AGENTS.md never mentioned it, so an agent reading
the canonical guide would not know it exists and would answer the same question
again somewhere else. Three additions:

- The repository-structure tree now lists docs/faq/ beside docs/release-notes/.
- Documentation conventions gain the rule: a question someone will ask again gets
  its own file in docs/faq/ plus a row in the index. Phrase the heading as the
  question a reader types, not as the name the code uses, and do not restate a
  setup or reference page. Where a fact could sit in both, pick one owner --
  docs/codex-setup.md owns installing and configuring codex, the FAQ owns the
  per-path recipes.
- The reference-doc list points at docs/faq/, and the write-it-down rule at the
  end of that section now names the FAQ as a destination alongside the model
  guide and the setup doc.

Every relative link in AGENTS.md resolves.
@aarora79
aarora79 merged commit 89bb8a8 into main Sep 11, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant