# Story: Classify docs and tighten package documentation contents

Backlog Item ID: DOCS-PUBLIC-INTERNAL-PACKAGE-HYGIENE

## User Story

As a release manager, I want documentation classified as public, internal,
backlog, experiment, or package-required so that the public site and npm package
ship only the documentation intended for users while internal planning artifacts
remain available in the repository.

## Background

The public site does not currently render all files under `docs/`; it links to a
small subset and serves its own `site/public/architecture.mmd`. The npm package,
however, includes the full `docs/` tree through `package.json.files`. As
backlog, prompt-bank experiments, diagram experiments, and internal dogfooding
notes grow, package contents can become noisy.

Before final release, Open Orchestra should define which docs are:

- public user documentation;
- public package documentation;
- internal product/backlog material;
- experiment/provenance artifacts;
- site-only assets.

## Acceptance Criteria

- Inventory all files under `docs/` and classify each as public, internal,
  backlog, experiment, diagram artifact, or package-required.
- Identify which docs are linked from README.
- Identify which docs are linked from the public site.
- Identify which docs are required by runtime/package behavior.
- Decide whether `package.json.files` should include all docs or a narrower
  allowlist.
- If narrowing package contents, update `package.json.files` and validate with
  `npm pack --dry-run`.
- Preserve repository traceability for internal/backlog/experiment docs even if
  they are excluded from npm.
- Document the classification policy so future docs land in the right location.

## Non-Goals

- Redesigning the public site.
- Deleting historical evidence or backlog without an explicit archive decision.
- Moving docs into a SaaS registry.

## Suggested Implementation

- Add a docs classification manifest or policy document.
- Optionally reorganize directories only when links can be updated safely.
- Update `package.json.files` if package hygiene requires it.
- Run `npm pack --dry-run` and verify expected docs are included/excluded.

## T-Shirt Size

S

## Suggested Owners

Technical Writer, Release Manager, Product Owner.