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.

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/."

website/communitySidebars.ts

@@ -1,33 +1,25 @@
 import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
 
-/**
- * Creating a sidebar enables you to:
- - create an ordered group of docs
- - render a sidebar for each doc of that group
- - provide next/previous navigation
-
- The sidebars can be generated from the filesystem, or explicitly defined here.
-
- Create as many sidebars as you want.
- */
+// The documentation-standards content is vendored from the .github submodule
+// (symlinked), so we can't drop a _category_.json inside it to set the
+// sidebar label — it's wired up explicitly here instead (same pattern as
+// developSidebars.ts for the per-component vendored docs).
 const sidebars: SidebarsConfig = {
-  // By default, Docusaurus generates a sidebar from the docs folder structure
-  communitySidebar: [{type: 'autogenerated', dirName: '.'}],
-
-  // But you can create a sidebar manually
-
-//   guidesSidebar: [
-//     {
-//       type: 'category',
-//       label: 'moduleA',
-//       items: ['moduleA/nestedFolder/nestedElement'],
-//     },
-//     {
-//       type: 'category',
-//       label: 'moduleB',
-//       items: ['moduleB/littleBlackSubmarines'],
-//     },
-//   ],
+  communitySidebar: [
+    'support',
+    'team',
+    'funding',
+    'licensing',
+    'code-of-conduct',
+    'contribution',
+    'citing-us',
+    {
+      type: 'category',
+      label: 'Documentation Standards',
+      link: {type: 'doc', id: 'documentation-standards/documentation-standards'},
+      items: [{type: 'autogenerated', dirName: '07-documentation-standards'}],
+    },
+  ],
 };
 
 export default sidebars;

website/deploySidebars.ts

@@ -0,0 +1,18 @@
+import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
+
+const sidebars: SidebarsConfig = {
+  // Prelude and Quickstart are marked `unlisted` (hidden for now, still
+  // reachable by direct link) so they're left out here rather than
+  // autogenerated. The 3 deployment guide pages are hoisted to the sidebar
+  // root instead of nested under a "Deployment Guide" category/dropdown;
+  // their own overview page (deployment/index) is unlisted too, so it's
+  // left out here as well.
+  deploySidebar: [
+    "index",
+    "deployment/authorization",
+    "deployment/data-management-storage",
+    "deployment/search-portal",
+  ],
+};
+
+export default sidebars;

website/developSidebars.ts

@@ -0,0 +1,39 @@
+import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
+
+// Each component's docs are vendored from its own submodule (symlinked), so we
+// can't drop a _category_.json inside them to set the sidebar label. Instead
+// each is wired up explicitly here, paired as "Overture name (functional
+// name)" per the site map convention.
+const components: Array<{ dirName: string; id: string; label: string }> = [
+  {
+    dirName: "01-Lectern",
+    id: "Lectern",
+    label: "Lectern (Dictionary Management)",
+  },
+  { dirName: "02-Lyric", id: "Lyric", label: "Lyric (Data Management)" },
+  { dirName: "03-Song", id: "Song", label: "Song (File Management)" },
+  { dirName: "04-Score", id: "Score", label: "Score (File Transfer)" },
+  { dirName: "05-Maestro", id: "Maestro", label: "Maestro (Indexing)" },
+  { dirName: "06-Arranger", id: "Arranger", label: "Arranger (Search)" },
+  { dirName: "07-Stage", id: "Stage", label: "Stage (Portal UI)" },
+];
+
+const sidebars: SidebarsConfig = {
+  developSidebar: [
+    "index",
+    ...components.map(({ dirName, id, label }) => ({
+      type: "category" as const,
+      // Scoped by className so the "Overture name (functional name)" pairing
+      // (long enough to wrap on some of these) can get its own sidebar
+      // styling in custom.css without affecting other sidebars.
+      className: "sidebar-component-item",
+      label,
+      link: { type: "doc" as const, id: `${id}/overview` },
+      items: [{ type: "autogenerated" as const, dirName }],
+    })),
+    "api-reference",
+    "contributing",
+  ],
+};
+
+export default sidebars;