Overture docs V2 update

.gitignore

@@ -18,3 +18,7 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+# Project Management Context
+/CCDdoc
+/.dev

AGENTS.md

@@ -0,0 +1,30 @@
+<!-- agentics-template-version: 0.9.0 | synced: b37cb60ff2668945f74347826ca6ccf24b5e80a9 -->
+# Agent collaboration conventions — Overture Docs
+
+**For AI agents:** this file is instructions you read and follow, not documentation written for people. If you're a person, see [README.md](README.md) instead.
+
+Adapted from [softeng/agentics](https://github.com/oicr-softeng/agentics). This is the canonical, agent-neutral source for **Overture Docs-specific** conventions; `CLAUDE.md` is a stub that points here.
+
+Universal conventions (interaction style, critical constraints, testing, code style, security, documentation, session discipline), the developer role, the softeng team layer, and the Overture product-family layer (`CLAUDE.overture.md`, applied because project memory flags this as an Overture repo) are **not duplicated here**: they come from the developer's agentics-based global context and the local clone at `~/.claude/agentics/template/`. Any agent working in this repo reads those on demand; this file adds only what is specific to Overture Docs.
+
+## Session start
+Before touching content, read `.dev/roadmap.md`, `.dev/tech-debt.md`, and the most recent file(s) in `.dev/sessions/`. Full session-start sequence: `~/.claude/agentics/template/conventions/session-discipline.md`.
+
+## When to read what (agentics conventions — read on demand)
+The canonical task→convention dispatch table lives in `~/.claude/agentics/template/AGENTS.md` § "When to read what": tests, code style, code review, docs, security, convention levels, upgrading adoption. Read the matching file from `~/.claude/agentics/template/conventions/` when doing that task. Most work here is documentation, so `conventions/documentation.md` applies to the majority of changes.
+
+## Project context
+Overture Docs is the **centralized documentation site for the Overture stack**, built with [Docusaurus](https://docusaurus.io/). It aggregates Markdown from the `/docs` directory of each Overture project repository (pulled in as git submodules) and renders them as one navigable site. The point of the setup is that documentation stays with its source project while readers get a single hub. Full overview in [README.md](README.md); planned work lives in `.dev/roadmap.md`.
+
+## Project-specific constraints
+- **Public repository** (`overture-stack/docs`): no credentials, secrets, tokens, or private URLs in any committed file, ever.
+- **Documentation content is owned by the submodules, not this repo.** Each project's docs live in `submodules/<project>/docs/` and are symlinked into `website/docs/`. Edit the **source** file under `submodules/<project>/`, never the symlinked copy under `website/docs/`: editing through the link mutates the vendored submodule's working tree in a way that is easy to lose and confusing to review. Symlinks are (re)generated by `symlinker.sh`.
+- **Submodules are separate Overture repos with their own conventions.** Defer to any in-tree `AGENTS.md`/`CLAUDE.md` inside a submodule; do not apply this repo's root conventions on top of vendored component code. Changes to a submodule's actual content belong in that submodule's own repo and PR flow, not here.
+- **Only site scaffolding and aggregation live in this repo**: the Docusaurus config, theme, components, and the symlink/build wiring under `website/`. That is what a change to *this* repo (as opposed to a submodule) should normally touch.
+
+## Repository orientation
+- `submodules/` — vendored Overture repos as git submodules: `arranger`, `lectern`, `lyric`, `maestro`, `score`, `song`, `stage`, and `.github`. Each carries its own `/docs`. Defined in `.gitmodules` (see `.dev/roadmap.md`: release-branch tracking is not yet configured, so `git submodule update --remote` currently follows each repo's default branch).
+- `website/` — the Docusaurus site: `docs/` (aggregated, symlinked from submodules), `community/`, `guides/`, and `src/` (`components/`, `css/`, `theme/`, `pages/`).
+- `symlinker.sh` — regenerates the symlinks that bring selected submodule `/docs` files into `website/docs/`.
+- `README.md`, `preview.png` — human-facing project overview and screenshot.
+- Local setup: Node 18+, `npm ci`, then `npm start` (see `README.md` § Getting Started).

CLAUDE.md

@@ -0,0 +1,7 @@
+# Agent collaboration conventions
+
+**For AI agents:** this file is instructions your agent reads and follows; it is not documentation written for people. If you're a person looking for how this project works, see [README.md](README.md) instead.
+
+Adapted from [softeng/agentics](https://github.com/oicr-softeng/agentics).
+
+This file exists only because Claude Code loads it automatically; it is not the canonical source. Read [AGENTS.md](AGENTS.md) now for this project's conventions. Universal conventions, your role, and the softeng team layer come from your global context (`~/.claude/CLAUDE.md`) and the agentics clone at `~/.claude/agentics/template/`, so none of it is duplicated here to drift out of sync.

README.md

@@ -11,7 +11,7 @@ Overture Docs is a centralized documentation site built with [Docusaurus](https:
 
 ### Running it Locally
 
-1. clone the repository with the submodules:
+1. Clone the repository with the submodules:
 
 ```bash
 git clone --recurse-submodules https://github.com/overture-stack/docs.git
@@ -20,66 +20,92 @@ git clone --recurse-submodules https://github.com/overture-stack/docs.git
 > [!TIP]
 > Already cloned the repo? You can still get the submodules by running: `git submodule update --init --recursive`
 
-2. Install required dependencies:
+2. Install required dependencies from the `website` directory:
 
-```
+```bash
+cd website
 npm ci
 ```
 
-Start the server
+3. Start the server:
 
-```
+```bash
 npm start
 ```
 
 > [!IMPORTANT]
-> Docusaurus requires node version 18 or higher
+> Docusaurus requires node version 18 or higher. All npm commands run from `website/`; there is no package manifest at the repository root.
 
 ## How Overture Docs Works
 
 - **Docusaurus**: We use Docusaurus to render the site, providing a sleek and navigable interface for our documentation.
 
-- **Markdown Files**: All documentation content is stored as markdown files in the `/website/docs` directory.
+- **Four documentation sections**: The site is organized around what a reader is trying to do, rather than around our repository layout. Each section is a separate Docusaurus docs plugin instance with its own content directory, route, and sidebar:
+
+    | Section   | Content                            | Route        | Sidebar                  |
+    | --------- | ---------------------------------- | ------------ | ------------------------ |
+    | Develop   | `website/docs/develop-docs/`       | `/develop`   | `developSidebars.ts`     |
+    | Deploy    | `website/docs/deploy-docs/`        | `/deploy`    | `deploySidebars.ts`      |
+    | Use       | `website/docs/use-docs/`           | `/use`       | `useSidebars.ts`         |
+    | Community | `website/docs/community-docs/`     | `/community` | `communitySidebars.ts`   |
+
+- **Markdown Files**: All documentation content is stored as Markdown (or MDX) files under `website/docs/`, within the section it belongs to.
 
-- **Git Submodules**: We use Git submodules to store and track all our GitHub repositories within one main repository. All submodules can be found in the `submodule` folder.
+- **Git Submodules**: We use Git submodules to store and track all our GitHub repositories within one main repository. All submodules can be found in the `submodules` folder.
 
-- **Symlinks**: Only the necessary documentation files are symlinked from the submodules in the `submodule` folder to the `/website/docs` directory. This allows us to import only the required markdown content that Docusaurus needs.
+- **Symlinks**: Only the necessary documentation files are symlinked from the submodules into `website/docs/`. This allows us to import only the required Markdown content that Docusaurus needs. The symlinks are generated by [symlinker.sh](symlinker.sh), which is the source of truth for what gets surfaced; run `./symlinker.sh` from the repository root after changing which submodule docs the site includes.
+
+- **Redirects**: Legacy URLs are preserved through `@docusaurus/plugin-client-redirects`, configured in [website/docusaurus.config.ts](website/docusaurus.config.ts), so older links and bookmarks continue to resolve.
+
+- **Interactive components**: Some pages embed browser-based tooling (the configuration generator, the Lectern dictionary playground, and the Song schema playground) built as React components under `website/src/components/`.
 
 ## Repository structure
 
 ```
 .
-├── /submodules/               # Core Repository Submodules
-│   ├── /.github/             # GitHub configurations, workflows and standards docs
-│   ├── /arranger/            # Arranger repository
-│   ├── /lectern/             # Lectern repository
-│   ├── /lyric/               # Lyric repository
-│   ├── /maestro/             # Maestro repository
-│   ├── /score/               # Score repository
-│   ├── /song/                # Song repository
-│   └── /stage/               # Stage repository
-│        └── /docs/           # Repository-specific documentation (found in every submodule repo)
+├── /submodules/                # Core Repository Submodules
+│   ├── /.github/               # GitHub configurations, workflows and standards docs
+│   ├── /arranger/              # Arranger repository
+│   ├── /lectern/               # Lectern repository
+│   ├── /lyric/                 # Lyric repository
+│   ├── /maestro/               # Maestro repository
+│   ├── /score/                 # Score repository
+│   ├── /song/                  # Song repository
+│   └── /stage/                 # Stage repository
+│        └── /docs/             # Repository-specific documentation (found in every submodule repo)
+│
+├── symlinker.sh                # Regenerates the submodule doc symlinks under /website/docs/
 │
-└── /website/                  # Documentation Website
-    ├── /community/           # Community resources and guidelines
-    ├── /docs/                # Aggregated documentation (symlinked from submodules)
-    ├── /guides/              # Overture platform user guides
-    └── /src/                 # Website source code
-        ├── /components/      # React components
-        ├── /css/            # Component-specific styles
-        ├── /theme/          # Global theme configuration and styling
-        └── /pages/          # Static page content
+└── /website/                   # Documentation Website
+    ├── /docs/                  # All documentation content, split by reader journey
+    │   ├── /develop-docs/      # Per-component developer docs (symlinked from submodules)
+    │   ├── /deploy-docs/       # Prelude and deployment documentation
+    │   ├── /use-docs/          # Guides, workshop, administration, playgrounds
+    │   └── /community-docs/    # Community resources, guidelines and standards
+    ├── /remark/                # Custom remark plugins applied to vendored content
+    ├── /src/                   # Website source code
+    │   ├── /components/        # React components
+    │   ├── /css/               # Component-specific styles
+    │   ├── /theme/             # Global theme configuration and styling
+    │   └── /pages/             # Static page content
+    ├── /static/                # Static assets served as-is
+    ├── docusaurus.config.ts    # Site config: plugin instances, navbar, redirects
+    └── *Sidebars.ts            # One sidebar file per documentation section
 ```
 
 ### Key Directories
 
 - **/submodules/**: Contains all Overture core repositories as Git submodules
 - **/website/**: Houses the Docusaurus-powered documentation website
-    - **/community/**: Community-focused content and resources
-    - **/docs/**: Central location for all documentation, automatically linked from repository submodules
-    - **/guides/**: Comprehensive platform guides and tutorials
+    - **/docs/develop-docs/**: Component-level documentation, automatically linked from repository submodules
+    - **/docs/deploy-docs/**: How to stand up and configure an Overture deployment
+    - **/docs/use-docs/**: Task-oriented content for people working with a running platform
+    - **/docs/community-docs/**: Community-focused content, including the org-wide documentation standards linked from the `.github` submodule
     - **/src/**: Website implementation files including custom components, styling, and page content
 
+> [!IMPORTANT]
+> Documentation content is owned by the submodules, not by this repository. Where a page under `website/docs/` is a symlink, edit the source file in `submodules/<project>/docs/` and land the change through that project's own repository.
+
 ## Benefits of this Setup
 
 - **A Centralized Resource for Decentralized Documentation**: A single, easy-to-navigate hub displaying all our developer documentation while keeping all documentation markdown files within their respective repositories.
@@ -90,7 +116,5 @@ npm start
 
 - **Robust Error Handling**: Docusaurus has excellent error catching, particularly for broken and missing links, reducing the need for manual testing.
 
-![Pro Tip](./website/docs/02-platform-tools/images/proTip.png 'Use Overture Docs repo to search across all Overture repos')
-
 > [!TIP]
 > The Overture Docs repo contains everything, therefore finding & tracking links and content across all our repos has never been easier.

symlinker.sh

@@ -1,16 +1,43 @@
-#!/bin/bash
+#!/usr/bin/env bash
+#
+# Regenerates the documentation symlinks under website/docs/ that bring each
+# submodule's docs into the Docusaurus site. Run from the repository root:
+#
+#     ./symlinker.sh
+#
+# These links MUST match what is committed under website/docs/. If you change
+# what the site surfaces, change it here and regenerate — so the script and the
+# repo never disagree. (A drifted script silently rebuilds a *different* site.)
+#
+# Link targets are relative, never absolute: Netlify resolves them at build time
+# and absolute paths do not deploy correctly.
+#
+set -euo pipefail
+cd "$(dirname "$0")"
 
-# Do not use absolute paths, they will not deploy on netlify correctly
-# Run this from the directory you want the link to be made in 
-ln -s ../../../submodules/song/docs/ 01-song
-ln -s ../../../submodules/score/docs/ 02-score
-ln -s ../../../submodules/maestro/docs/ 03-maestro
-ln -s ../../../submodules/arranger/docs/ 04-arranger
-ln -s ../../../submodules/stage/docs/ 05-stage
+# --- Core software: each links the component's whole docs/ directory ---
+#     link path (under website/docs/)                 submodule
+core_links=(
+  "website/docs/develop-docs/01-Lectern     lectern"
+  "website/docs/develop-docs/02-Lyric       lyric"
+  "website/docs/develop-docs/03-Song        song"
+  "website/docs/develop-docs/04-Score       score"
+  "website/docs/develop-docs/05-Maestro     maestro"
+  "website/docs/develop-docs/06-Arranger    arranger"
+  "website/docs/develop-docs/07-Stage       stage"
+)
+for entry in "${core_links[@]}"; do
+  read -r link comp <<<"$entry"
+  rm -rf "$link"
+  ln -s "../../../submodules/${comp}/docs/" "$link"
+done
 
-# Linked into from bridge/website/docs/04-Standards
-ln -s ../../submodules/.github/standards 04-standards
+# --- Org-level documentation standards (from the .github submodule) ---
+#     Re-homed under the Community journey (website/docs/community-docs/) in
+#     the Deploy·Build·Use IA migration; the relative target has one fewer
+#     ../ than the core_links above because this symlink sits directly under
+#     docs/community-docs/, not nested a level deeper like 01-core-software/.
+rm -rf "website/docs/community-docs/07-documentation-standards"
+ln -s "../../../submodules/.github/standards" "website/docs/community-docs/07-documentation-standards"
 
-# Linked into from bridge/website/docs/03-under-development 
-ln -s ../../../submodules/lectern/docs/overview 01-lectern
-ln -s ../../../submodules/lyric/docs/ 02-lyric
+echo "Regenerated $(( ${#core_links[@]} + 1 )) doc symlinks under website/."