OpenShell/README.md

OpenShell Docs Website Branch

This branch contains the generated Fern documentation website for OpenShell. It is intentionally separate from main and does not contain the OpenShell application source tree.

Purpose

docs-website is the publishable docs branch. The branch stores versioned Fern snapshots so the docs site can serve the current release, current development docs, and selected historical releases from one generated branch.

Do not use this branch for source changes. Update documentation source on main, then sync the desired snapshot into this branch.

Current Snapshots

Version	Source
latest	v0.0.57
dev	main snapshot
v0.0.36	v0.0.36

Expected routes:

• /openshell/latest/... renders the current release snapshot.
• /openshell/dev/... renders the current development docs snapshot.
• /openshell/v0.0.36/... renders the selected historical snapshot.

latest is a moving release alias. It is not a dedicated historical route for the release tag it currently points at.

Layout

fern/
├── docs.yml
├── versions/
│   ├── dev.yml
│   ├── latest.yml
│   └── v0.0.36.yml
├── pages-dev/
├── pages-latest/
└── pages-v0.0.36/

fern/docs.yml defines the public version selector and the shared Fern site configuration. Each fern/versions/*.yml file points navigation entries at the matching fern/pages-* snapshot directory.

Sync Model

The planned automation on main owns this branch:

1. sync-docs.yml checks out a source ref from main or a release tag.
2. The sync script copies docs/** into the selected fern/pages-{slug}/ directory.
3. The sync script updates fern/versions/{slug}.yml and the version list in fern/docs.yml.
4. Fern validation runs before the generated changes are committed back to this branch.
5. publish-docs-website.yml publishes this branch to Fern in preview or production mode.

Historical snapshots are preserved until their slug is explicitly synced or removed. Removing a version deletes only its fern/pages-{slug}/ directory, its fern/versions/{slug}.yml file, and its version selector entry.

Validation

Run Fern validation:

mise run docs

Run a local Fern preview:

mise run docs:serve

If FERN_TOKEN is available, run a non-production hosted preview:

npx --yes fern-api@5.40.0 generate --docs --preview --id openshell-docs-website

Included Root Files

The root LICENSE, CONTRIBUTING.md, and SECURITY.md files are copied from main so the generated branch keeps the repository's normal license, contribution, and security reporting signals.

Branch Rules

Recommended protection for this branch:

• Prevent deletion.
• Prevent force pushes.
• Allow maintainers and the docs sync workflow to push generated updates.
• Avoid requiring normal pull request review for generated sync commits until the manual sync and publish path is proven stable.