# Train Online documentation

Everything in `docs/` is public, committed, and included in the generated documentation site.
Do not put secrets or private working notes here. Keep private notes in ignored
`dev-docs/`. Edit the public pages here; older copies in `dev-docs/` are not the
publication source.

## Site structure and CSS

- `index.html`: navigation homepage.
- `product-journeys.html`: product flow and wireframes.
- `architecture.html`: system diagram and component descriptions.
- `PLAN.md`, `architecture.md`, `cost-model.md`: public working-plan sources.
- `css/styles.css`: shared documentation navigation and homepage styling.
- `css/architecture.css`: architecture page layout and diagram styles.
- `css/product-journeys.css`: product page layout and journey states.
- `css/wireframe-design-system.css`: documentation-only wireframe adapters.
- Top-level `styles/`: canonical product tokens, components, and workbench CSS.
- `scripts/build-docs.mjs`: dependency-free Node.js 22 documentation build.

The app imports `styles/index.css` through `web/src/index.css`. Product docs
load the same entry point at `styles/index.css` in the generated site. Shared
controls use `.ui-button` and are scoped to `.app-shell` or `.train-ui`.
Wireframe-only states and simulated code remain in documentation CSS; Monaco
continues to render the real editor. Application resets stay app-only.

Do not edit CSS in `dist-docs/`: it is generated and ignored. Compatibility
imports in `web/src/design/` forward to the shared source. Markdown links serve
source documents rather than generated HTML pages.

## Build and local preview

From the repository root, using Node.js 22:

```sh
node scripts/build-docs.mjs
python3 -m http.server 8000 --directory dist-docs
```

Open http://localhost:8000/ and check the HTML pages and navigation. Rebuild
after changes to `docs/` or `styles/`. The build replaces `dist-docs/` with only
public docs and CSS, and works independently of app dependencies. Previewing
`docs/` directly no longer includes the shared CSS.

## Intended Cloudflare Pages settings

- Product: Cloudflare Pages (Git integration), not Workers.
- Production branch: `main`.
- Framework: None.
- Root directory: repository root.
- Build command: `node scripts/build-docs.mjs`.
- Build runtime: Node.js 22 (set `NODE_VERSION=22`).
- Build output directory: `dist-docs`.
- Include watch paths: `docs/*`, `styles/*`, `scripts/build-docs.mjs`.
- Exclude watch paths: none.
- [Cloudflare Pages wildcard rules](https://developers.cloudflare.com/pages/configuration/build-watch-paths/)
  match `/`, so the directory patterns include nested files.

## Verified deployment

- Project: `train-online-docs`.
- Public URL: https://train-online-docs.pages.dev/ .
- Initial production commit: `ec73cb7` on `main`.
- Deployment ID: `6c419872-8074-4044-8efd-b59b061be325`.
- Cloudflare reported success; all 15 deployed HTML, CSS, and Markdown files
  matched the local build and loaded without authentication.
- Unknown paths currently return the homepage through Pages fallback behavior;
  checked private repository paths did not expose repository content.
- Automatic deployments and the listed watch paths are saved and verified.
  A push-triggered update was verified for commit `11fdcf3` (deployment
  `83db04fc-dd80-4681-82cf-bb0aa0b45182`): Cloudflare reported success and the
  temporary text appeared on the public homepage. The test text is removed
  from the source.


## Normal update workflow

Review `git diff` and stage only the intended public documentation changes:

```sh
git add docs/ styles/ scripts/build-docs.mjs
git commit -m "Update documentation"
git push origin main
```

Push approved documentation updates to `main`; Cloudflare builds and deploys
automatically when a watched file changes. Review the deployment result in
Cloudflare and check the production URL.