Medication Tracker

Documentation and the /docs knowledge base

This skill expands section 16 of AGENTS.md. Read that section and the project-preferences skill first. Follow the wording rules in the response-style skill and the reading level in section 12 of AGENTS.md. The README stays short, per section 15; detail belongs here.

/docs is a small curated knowledge base for humans and for agents arriving with no context. It is not generated API reference, so no autodoc dumps, no per-function pages, and no restated docstrings. Section 5 of AGENTS.md covers documenting interfaces in the code itself.

Pages

Create the pages that apply and skip the rest. An empty stub is worse than a missing page.

/docs
README.md           Index of this folder: one linked line per page
architecture.md     Components, what each does, how they connect, key decisions and why
data-flow.md        Where data enters, how it changes, where it lands; formats, schemas, time zones; where PHI could appear and how it is protected
usage.md            Common operations beyond the README quick start
how-to/             One file per goal, such as how-to/add-a-data-source.md
troubleshooting.md  Known failure modes: symptom, cause, fix
faq.md              Questions people actually asked, with answers
compliance.md       Security and accessibility posture: controls in place, WCAG target and evidence, data retention, known gaps, review status

Page structure

Every page uses this order.

The hidden license header, an HTML comment at the top, after required YAML frontmatter when present, invisible when rendered:

<!--
This file is part of Medication Tracker
Copyright © YYYY Gabriel Mongefranco
Licensed under the GNU Free Documentation License v1.3 or later.
See <https://www.gnu.org/licenses/fdl-1.3.html>. See README for full license information.
-->

The project title as H1.
The page subtitle as H2.
A link back to the project README, directly under the subtitle, relative to this page’s depth: ../README.md from /docs, ../../README.md from /docs/how-to/.
A summary of two to four plain-language sentences covering what the page holds and who it is for. Someone who stops reading here still knows whether they are in the right place.
The body, as sections, numbered steps, or both.
A short conclusion saying what the reader can now do and where to go next.
Additional resources: every link used in the page, plus related project documentation and outside references, all with descriptive link text.
The same relative link back to the project README as the last line.

Content rules

Write for a capable maintainer, researcher, or auditor who has never seen the project.
Document only behavior that exists and can be checked against the current code or configuration. Put anything planned under a clearly labeled “Planned” note.
Use synthetic examples for all sample data, identifiers, credentials, and paths, per sections 6 through 8 of AGENTS.md.
Prefer Mermaid for architecture and data-flow diagrams so diffs stay reviewable, and always pair a diagram with an equivalent text description. See the accessibility skill.
Earn troubleshooting and FAQ entries. Add one when a real failure or question happens, or when the design makes it clearly predictable. Never pad with invented hypotheticals.
Keep compliance.md to evidence rather than aspiration. “Inputs validated via allowlist in config/validation.js; axe-core scan clean as of " is acceptable. "Fully HIPAA compliant" is not.

When to update

Update /docs in the same change set whenever any of these happen:

Functionality is added or removed.
User-visible behavior changes: inputs, outputs, defaults, error messages, steps, or interface.
Configuration, dependencies, permissions, or the run or deploy procedure changes.
Data structures change: schema, grain, field meaning, units, time zone, or retention.
Security or accessibility posture changes, which also means compliance.md.
The changes have piled up enough that a new hire reading only the old pages would be misled.

A small internal refactor with no user-visible or structural effect needs no documentation update. When you do update pages, name them in the Summary of your response. Stale documentation is a defect.