# Documentation Site

## Objective

Publish structured docs with a nested sidebar, linkable headings, and selectable versions.

A documentation site with a nested navigation tree, per-page heading anchors, and versioned content.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Define the sidebar tree explicitly as ordered content, not by inferring it from file names or page titles. An inferred tree silently drops pages when someone renames one.
2. Generate an anchor for every heading and derive it from the heading text, but store the anchor once it has been published so renaming the heading does not break links people have already shared.
3. Reuse the app's existing table of contents behaviour for the in-page heading list rather than writing a second scroll-spy, and reuse the existing search rather than adding a docs-only one.
4. Make versioning a property of the whole documentation set with one current version and a small number of archived ones. Do not build per-page version branching until there is a real need for it.
5. Do not paste examples in as screenshots. Code and configuration must be selectable text so a reader can copy it, and must carry a language label for syntax rendering.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- A page that exists in the content store but sits nowhere in the sidebar tree is unreachable by browsing. Surface those orphans to authors rather than letting them go quietly missing.
- Renaming a heading changes its anchor and silently breaks every deep link to that section. Keep the previous anchor as an alias on the same heading.
- A reader on an older version who follows a link to a page that only exists in the latest version must be told the page is not in their version and offered the latest, not dropped on a not-found page.
- Long code blocks must scroll horizontally inside their own container. The page body itself must never scroll sideways on a phone.
- Arriving from a deep link must open the sidebar to the section containing that page and scroll it into view, otherwise the reader has no idea where they are in the tree.
- Switching versions from a page should land on the same page in the target version when it exists, and on that version's index when it does not.
- Search results must be scoped to the selected version, or readers will keep landing on documentation for software they are not running.
- The archived versions must carry a visible notice that they are not current, with a link to the latest.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] The sidebar renders a nested tree with the current page and its ancestors expanded.
- [ ] Every heading has a copyable anchor link, and previously published anchors keep working after a rename.
- [ ] Version switching preserves the current page when it exists in the target version.
- [ ] Code blocks scroll within their container and the page never scrolls horizontally at 320px.
- [ ] Search results are limited to the selected version.
- [ ] Pages absent from the navigation tree are reported to authors.
- [ ] Archived versions display a notice pointing to the current version.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.