# Roadmap: v0.7.6 Documentation Structure

## Status

Planned

## Requirement

REQ-Documentation-Structure

## Context

RAC currently contains multiple types of knowledge:

- Public documentation
- Internal product artifacts
- Architecture decisions
- Roadmaps
- Implementation context

As the project grows, these concerns need clearer ownership boundaries.

RAC should demonstrate its own philosophy by organizing knowledge intentionally.

Documentation should help users understand RAC quickly without requiring them to understand RAC's internal planning process.

## Goal

Introduce the canonical repository documentation structure:

```text
README.md

docs/

rac/

src/

tests/
```

where:

- README.md introduces the project.
- docs/ teaches users how to use RAC.
- rac/ contains RAC's dogfooded knowledge corpus.

## Scope

### Add User Documentation Layer

Create:

```text
docs/
  quickstart.md
  cli.md
  artifacts.md
  relationships.md
  repo-workflow.md
  testing.md
  examples.md
```

Each document should be task-oriented rather than implementation-oriented.

---

### docs/quickstart.md

Must answer:

> How do I try RAC in five minutes?

Include:

- Installation
- First artifact
- Validation example
- Inspection example
- Expected output

---

### docs/cli.md

Must document:

- Commands
- Purpose
- Inputs
- Outputs
- Common examples

Commands (full reference in docs/cli.md):

- validate
- diff
- stats
- ingest
- inspect
- improve
- schema
- relationships
- portfolio
- index

---

### docs/artifacts.md

Must explain supported RAC artifacts:

- Requirements
- Decisions (ADRs are Decisions written in ADR format)
- Roadmaps
- Prompts
- Designs

Include:

- Purpose
- Expected structure
- Naming guidance

---

### docs/relationships.md

Must explain:

- Artifact identifiers
- References
- Relationship validation
- Broken links
- Repository consistency

---

### docs/repo-workflow.md

Must document RAC repository conventions.

Example:

```text
rac/
  requirements/
  decisions/
  designs/
  prompts/
  roadmaps/
  assets/
```

Include workflows:

```bash
rac stats rac/
rac relationships rac/ --validate
rac portfolio rac/
```

---

### docs/testing.md

Must explain:

- Local setup
- Test execution
- Contributor verification workflow

---

### docs/examples.md

Must provide small realistic examples.

Avoid replacing templates.

## Non-Goals

This release does not:

- Change CLI behavior.
- Add artifact types.
- Change validation rules.
- Change schemas.
- Add documentation hosting.

## Acceptance Criteria

- docs/ exists with required files.
- Documentation is user-focused.
- Internal RAC artifacts remain under rac/.
- Users can understand RAC without reading roadmap files.
- Contributors can find testing instructions.

## Validation

Run:

```bash
rac stats rac/
rac relationships rac/ --validate
pytest
```

Note: `rac validate` checks a single file; use `rac stats rac/` for tree-wide health.

## Release

Target:

v0.7.6