[Epic] Make Theme Elementary documentation comprehensive and easy to use

[divyarajmasani]

Summary

Organize documentation around the developer's journey: start a project, understand what the skeleton includes, modify an example, add functionality, and resolve common failures. Provide enough context to complete these tasks without requiring developers to read framework source.

Branch baseline

Use theme-elementary-v2 as the base branch for this epic and every sub-issue. Document the functionality introduced on that branch and subsequent changes built on it; do not use main as the implementation reference. Before writing or validating a guide, check the latest relevant v2 changes and record the branch and commit tested in the documentation PR.

Documentation ownership

• Theme Elementary: what ships, where files belong, initialization, local workflows, integration examples, and troubleshooting specific to the skeleton.
• wp-framework: detailed class contracts, inherited methods, lifecycle, APIs, and full framework tutorials.
• wp-tooling: generic scaffold catalogue, engine behavior, and exhaustive command options.

Link directly to relevant, version-compatible upstream documentation. Do not reproduce those references locally or require developers to search upstream homepages.

Documentation map and sub-issues

Document	Purpose	Issue
README.md	Brief overview and task-based navigation	01 — README
docs/getting-started.md	One tested route to a running theme	02 — Getting started
docs/initialization.md	Prompts, changes, cleanup, and later management	03 — Initialization
docs/local-development.md	Daily editing, builds, checks, and troubleshooting	04 — Local development
docs/scaffolding.md	One feature generated through CLI and AI	05 — Scaffolding
docs/features.md	Built-in infrastructure, examples, and optional features	06 — What is included
DEVELOPMENT.md	Short worked examples for extending the project	07 — Extending the theme
docs/internal/	Release validation and dependency development	08 — Internal documentation

• 01 — Make the README a concise documentation entry point.
• 02 — Add one verified route to a running theme.
• 03 — Explain initialization prompts, changes, and later management.
• 04 — Document the daily local-development workflow.
• 05 — Explain CLI and AI scaffolding through one feature.
• 06 — Explain what the skeleton includes.
• 07 — Document extending the theme with short worked examples.
• 08 — Separate maintainer procedures from developer onboarding.

Shared editorial requirements

• Give each page one task and a clear outcome; put advanced material behind links.
• Keep one canonical home for each procedure. Getting Started composes the minimum steps; reference pages provide detail.
• Each example answers: where does it go, what changes, how does it become active, and how is success checked?
• State the working directory and distinguish standalone setup from an existing WordPress/VIP repository. Link to project-level instructions for full VIP setup.
• Explain AI and CLI as alternative entry points; make their differing outputs and remaining work explicit.
• Use brief symptom → check → next action troubleshooting entries.
• Include review checkpoints after personalization and feature completion. Suggest separate baseline and feature commits without imposing a history policy.
• Verify commands against theme-elementary-v2 and subsequent work based on it; test the user journeys in a disposable project and record the tested commit.
• Keep links valid when documents move or downstream cleanup removes files; update old entry points.
• Keep pilot workarounds separate and time-bound. Do not publish hypothetical stable commands as working instructions.

Acceptance criteria

• A first-time developer can start a project and see the theme running.
• They can identify supplied functionality, editable source files, and generated output.
• They can adapt an example and add a feature through a supported manual or assisted route.
• They can resolve representative setup, registration, and asset failures using the guides.
• These tasks do not require reading framework source or a complete class reference.
• Commands and links have been checked, with validation results recorded in the documentation PR.
• Any missing upstream documentation or implementation blocker has a linked follow-up issue.

Implementation dependencies and exclusions

Cleanup failures, dependency-install behavior, scaffold wrappers, test-script fixes, and CI automation belong in separate implementation issues. Link concrete dependencies where they prevent a documented journey from working; do not silently expand documentation tasks into code changes.

This epic does not prescribe dynamic versus static blocks, redesign framework APIs, or duplicate framework/tooling manuals.