docs: add Corp pilot onboarding guide

docs/ways-of-working/index.md

@@ -0,0 +1,23 @@
+---
+title: "Ways of Working"
+description: "Use the shared operating practices for participating safely and effectively in the Corp v1 pilot."
+slug: /
+sidebar_position: 1
+---
+
+# Ways of Working
+
+Corp v1 is a governed AI-assisted delivery pilot. People set outcomes, authority, and constraints; Hermes helps turn those decisions into traceable designs, code, documentation, releases, and operated evidence.
+
+Use this area to understand how to join the pilot, where work belongs, how decisions become delivery, and which evidence is required before something is called complete.
+
+## Start here
+
+1. Read [Onboarding](./onboarding) before contributing.
+2. Find your project in the [project registry](/projects/).
+3. Confirm your responsibilities in the [team](/teams/) and [member](/members/) registries.
+4. Follow the [project lifecycle](/governance/project-lifecycle/) and the authority recorded for your project.
+
+## Core principle
+
+Keep conversation, decisions, implementation, deployment, and runtime proof connected—but do not treat them as the same thing. An approved idea is not implemented work; a merged change is not a deployed change; a healthy runtime is not release or product acceptance.

docs/ways-of-working/onboarding.md

@@ -0,0 +1,117 @@
+---
+title: "Onboarding"
+description: "Join the Corp v1 pilot with the right access, context, channel routing, authority, security practices, and evidence expectations."
+sidebar_position: 1
+---
+
+# Onboarding
+
+Use this page when joining the Corp v1 pilot or entering a project for the first time. You should finish with the right access, a clear role, and enough context to contribute without bypassing project governance.
+
+## What the pilot is
+
+Corp v1 tests whether one AI agent can support several focused project workstreams while people retain explicit authority and durable oversight. The pilot currently includes:
+
+- [AeroSim](/projects/aerosim/)
+- [Maze Next Gen](/projects/mazeng/)
+- [E-Shop v1](/projects/eshopv1/)
+
+The [Board](/board/) governs project kickoff, closure, and changes to the main Corp v1 operating model. Each project has its own sponsor, team, approved scope, repositories, documentation, Discord category, and preserved authority decisions.
+
+## Your first 20 minutes
+
+1. **Confirm your identity and role.** Check the [member registry](/members/) and your [team record](/teams/). If either is wrong, raise it before taking ownership of work.
+2. **Open the project record.** Read its purpose, initial deliverable, current status, resources, and outstanding gates in the [project registry](/projects/).
+3. **Open the project documentation.** It is the durable source for scope, architecture, design, Kanban state, ways of working, engineering guidance, and release evidence.
+4. **Verify Discord access.** Every project has one dedicated `corp-v1-<code>` category with seven lifecycle channels. Confirm that you can see the channels needed for your role and read their pinned guidance.
+5. **Verify Gitea access.** Confirm access to the project and skills organizations through the appropriate teams. Do not request direct repository access when team membership is the intended route.
+6. **Choose one current outcome.** Start from an existing Epic, Feature, task, issue, design package, or release gate. Do not create parallel records because an item is difficult to find.
+
+## Use the seven channels correctly
+
+Work moves through this shared lifecycle:
+
+```text
+General → Scope → Architecture → UI/UX → Kanban → Delivery → Releases
+```
+
+| Channel | Use it for |
+|---|---|
+| **General** | Project-wide direction, coordination, questions, outcomes, and cross-channel issues |
+| **Scope** | Ideas, Epics, Features, value, acceptance outcomes, and product decisions |
+| **Architecture** | Solution design, interfaces, constraints, risks, and implementation task definitions |
+| **UI/UX** | User journeys, Penpot designs, responsive behavior, accessibility, and implementation handoff |
+| **Kanban** | Flow visibility, task admission, sequencing, dependencies, and blockers |
+| **Delivery** | Implementation, tests, reviews, CI, build health, and delivery evidence |
+| **Releases** | Version readiness, changelogs, deployment approval, rollout, rollback, and runtime verification |
+
+Post in the channel that owns the decision or artifact. Cross-link evidence instead of copying whole conversations between channels. Keep one project’s information inside that project’s seven-channel boundary unless a Board-level concern requires escalation.
+
+## Understand authority
+
+- **Board authority** covers project kickoff, project closure, and changes to `corp-v1--main`.
+- **Project-team authority** covers decisions inside the project’s approved boundary.
+- **Hermes authority** is project-specific. It may range from preparing proposals to full delegated delivery and merge authority. Use the preserved project record and channel skill; never infer authority from activity, silence, CI success, or an agent statement.
+- **Explicit gates remain explicit.** A decision must identify the item, actor, conditions, and evidence. Delegation changes who may decide; it does not remove security, quality, traceability, or validation gates.
+
+When authority is unclear, stop at a reversible proposal and ask in the owning channel.
+
+## Know what “done” means
+
+Keep these states separate:
+
+1. **Approved** — an authorized person or delegate accepted the exact scope or decision.
+2. **Implemented** — source changes exist and passed the required local/review checks.
+3. **Merged** — the reviewed change is integrated into the repository’s default branch.
+4. **Deployed / runtime verified** — the intended immutable revision is running and has passed live readback or acceptance checks.
+5. **Released / accepted** — the project’s release authority approved the version and required outcomes.
+
+Always state the highest level actually proven and link the evidence. Do not use “live” as a shortcut for release approval or product maturity.
+
+## Security and credentials
+
+- Never paste passwords, tokens, API keys, connection strings, secret values, or Bitwarden object metadata into Discord, issues, repositories, prompts, screenshots, or documentation.
+- Use the approved SSO and secret-injection paths. A credential being available does not authorize unrelated access, account administration, spending, or destructive work.
+- Record secret **names and readiness only** when governance requires it.
+- Report suspected exposure immediately in the owning project and follow the approved rotation path.
+- Treat private project repositories, project-channel history, and customer or operational data as project-bound information.
+
+## How to make a useful contribution
+
+A useful contribution is small enough to review and complete, but durable enough to help the next person:
+
+- start from a stable item or create a clearly marked proposal;
+- cite the source message, decision, requirement, design, issue, or runtime observation;
+- work in the owning channel and canonical repository;
+- preserve project naming, branch, testing, and documentation conventions;
+- run the required validation and match CI to the exact commit;
+- read back remote and deployed state before claiming completion;
+- report the outcome, evidence, remaining gates, owner, and next action concisely.
+
+If a task crosses channels, finish the source-owned result and hand off one clear requested action with evidence and unresolved risks.
+
+## Where truth lives
+
+| Information | Authoritative location |
+|---|---|
+| Portfolio governance, Board decisions, teams, and project registry | This Corp v1 portal |
+| Product scope and project delivery records | Project documentation repository and deployed documentation |
+| Source, reviews, commits, CI, and releases | Project Gitea repositories |
+| Discussion, approvals, coordination, and handoffs | Exact project Discord channels and message IDs |
+| Deployment and runtime state | GitOps source, Argo CD, workload state, and live acceptance evidence |
+| Editable interface design | Project-owned Penpot files linked from project records |
+
+No single status message replaces these sources. Reconcile them when they disagree.
+
+## Onboarding complete
+
+You are ready to contribute when you can answer:
+
+- Which project and outcome am I supporting?
+- What is my role and decision authority?
+- Which channel owns my next action?
+- Where is the canonical record?
+- What evidence is required before I call it complete?
+- Which security or release gates still apply?
+
+If any answer is missing, ask in the project’s **General** channel and link the record you already checked.

docusaurus.config.ts

@@ -39,6 +39,7 @@ const config: Config = {
     ['@docusaurus/plugin-content-docs', {...docsCommon, id: 'projects', path: 'docs/projects', routeBasePath: 'projects', sidebarPath: './sidebars/projects.ts'}],
     ['@docusaurus/plugin-content-docs', {...docsCommon, id: 'teams', path: 'docs/teams', routeBasePath: 'teams', sidebarPath: './sidebars/teams.ts'}],
     ['@docusaurus/plugin-content-docs', {...docsCommon, id: 'members', path: 'docs/members', routeBasePath: 'members', sidebarPath: './sidebars/members.ts'}],
+    ['@docusaurus/plugin-content-docs', {...docsCommon, id: 'ways-of-working', path: 'docs/ways-of-working', routeBasePath: 'ways-of-working', sidebarPath: './sidebars/ways-of-working.ts'}],
     ['@docusaurus/plugin-content-docs', {...docsCommon, id: 'board', path: 'docs/board', routeBasePath: 'board', sidebarPath: './sidebars/board.ts'}],
     ['@docusaurus/plugin-content-docs', {...docsCommon, id: 'governance', path: 'docs/governance', routeBasePath: 'governance', sidebarPath: './sidebars/governance.ts'}],
   ],
@@ -49,7 +50,7 @@ const config: Config = {
       indexDocs: true,
       indexBlog: false,
       indexPages: true,
-      docsRouteBasePath: ['/', 'architecture-high-level', 'projects', 'teams', 'members', 'board', 'governance'],
+      docsRouteBasePath: ['/', 'architecture-high-level', 'projects', 'teams', 'members', 'ways-of-working', 'board', 'governance'],
       language: ['en'],
       highlightSearchTermsOnTargetPage: true,
       explicitSearchResultPath: true,
@@ -63,6 +64,7 @@ const config: Config = {
       title: 'CORP V1 / BOARD',
       items: [
         {type: 'docSidebar', sidebarId: 'projectsSidebar', docsPluginId: 'projects', label: 'Projects', position: 'left'},
+        {type: 'docSidebar', sidebarId: 'waysOfWorkingSidebar', docsPluginId: 'ways-of-working', label: 'Ways of Working', position: 'left'},
         {type: 'docSidebar', sidebarId: 'teamsSidebar', docsPluginId: 'teams', label: 'Teams', position: 'left'},
         {type: 'docSidebar', sidebarId: 'membersSidebar', docsPluginId: 'members', label: 'Members', position: 'left'},
         {type: 'docSidebar', sidebarId: 'boardSidebar', docsPluginId: 'board', label: 'Board', position: 'left'},
@@ -76,6 +78,7 @@ const config: Config = {
       links: [{title: 'Registry', items: [
         {label: 'Architecture', to: '/architecture-high-level/context/'},
         {label: 'Projects', to: '/projects/'},
+        {label: 'Ways of Working', to: '/ways-of-working/'},
         {label: 'Teams', to: '/teams/'},
         {label: 'Members', to: '/members/'},
         {label: 'Board', to: '/board/'},

scripts/verify-portal.mjs

@@ -21,17 +21,30 @@ for (const section of ['projects', 'teams', 'members', 'board', 'governance']) {
   assert.match(config, new RegExp(`sidebarId:\\s*'${section}Sidebar'`), `${section} navbar item does not target its dedicated sidebar`);
   assert.ok(existsSync(join(root, `sidebars/${section}.ts`)), `${section} sidebar file is missing`);
 }
+assert.match(config, /id:\s*'ways-of-working'/, 'Ways of Working docs plugin is missing');
+assert.match(config, /sidebarId:\s*'waysOfWorkingSidebar'/, 'Ways of Working navbar item does not target its dedicated sidebar');
+assert.ok(existsSync(join(root, 'sidebars/ways-of-working.ts')), 'Ways of Working sidebar file is missing');
+assert.ok(existsSync(join(root, 'docs/ways-of-working/index.md')), 'Ways of Working entry page is missing');
+assert.ok(existsSync(join(root, 'docs/ways-of-working/onboarding.md')), 'Onboarding page is missing');
 assert.match(config, /id:\s*'architecture-high-level'/, 'Architecture High Level docs plugin is missing');
 assert.match(config, /sidebarId:\s*'architectureHighLevelSidebar'/, 'Architecture High Level navbar item does not target its dedicated sidebar');
 assert.match(config, /label:\s*'Architecture'/, 'Architecture navbar label is missing');
 assert.doesNotMatch(config, /label:\s*'Architecture High Level'/, 'legacy Architecture High Level menu label must not remain');
 assert.ok(existsSync(join(root, 'sidebars/architecture-high-level.ts')), 'Architecture High Level sidebar file is missing');
 
-const expectedLeftNavLabels = ['Projects', 'Teams', 'Members', 'Board', 'Governance', 'Architecture'];
+const expectedLeftNavLabels = ['Projects', 'Ways of Working', 'Teams', 'Members', 'Board', 'Governance', 'Architecture'];
 const leftNavLabels = [...config.matchAll(/\{type:\s*'docSidebar',[^\n]+label:\s*'([^']+)',\s*position:\s*'left'\}/g)]
   .map((match) => match[1]);
 assert.deepEqual(leftNavLabels, expectedLeftNavLabels, 'Architecture must be the final left-side menu item');
 
+const waysOfWorkingSidebar = read('sidebars/ways-of-working.ts');
+assert.match(waysOfWorkingSidebar, /link:\s*\{type:\s*'doc',\s*id:\s*'index'\}/, 'Ways of Working must link to its entry page');
+assert.match(waysOfWorkingSidebar, /items:\s*\[\{type:\s*'doc',\s*id:\s*'onboarding',\s*label:\s*'Onboarding'\}\]/, 'Onboarding must be the first child page');
+const onboarding = read('docs/ways-of-working/onboarding.md');
+for (const term of ['Your first 20 minutes', 'Use the seven channels correctly', 'Understand authority', 'Know what “done” means', 'Security and credentials', 'Onboarding complete']) {
+  assert.ok(onboarding.includes(term), `Onboarding is missing: ${term}`);
+}
+
 assert.match(config, /baseUrl:\s*'\/corp-v1\/portal\/'/, 'Pages base URL must follow the renamed repository');
 assert.match(config, /projectName:\s*'portal'/, 'Docusaurus project name must be portal');
 assert.doesNotMatch(config, /sterring-commitee/, 'legacy repository name must not remain in Docusaurus config');
@@ -68,7 +81,7 @@ assert.match(config, /indexPages:\s*true/, 'custom pages must be indexed');
 const searchRoutesMatch = config.match(/docsRouteBasePath:\s*\[([^\]]+)\]/);
 assert.ok(searchRoutesMatch, 'search route configuration is missing');
 const searchRoutes = searchRoutesMatch[1];
-for (const route of ['/', 'architecture-high-level', 'projects', 'teams', 'members', 'board', 'governance']) {
+for (const route of ['/', 'architecture-high-level', 'projects', 'teams', 'members', 'ways-of-working', 'board', 'governance']) {
   assert.ok(searchRoutes.includes(`'${route}'`), `search does not include route base ${route}`);
 }
 
@@ -145,7 +158,7 @@ if (existsSync(join(root, 'build'))) {
   const filename = readdirSync(join(root, 'build')).find((name) => /^search-index(?:-[a-f0-9]+)?\.json$/.test(name));
   assert.ok(filename, 'production search index is missing');
   const search = readFileSync(join(root, 'build', filename), 'utf8').toLowerCase();
-  for (const term of ['projects registry', 'teams registry', 'members registry', 'board members', 'project lifecycle', 'corp v1 board', 'container overview', 'operating model', 'overview channels', 'overview skills', 'overview repositories']) {
+  for (const term of ['projects registry', 'teams registry', 'members registry', 'board members', 'project lifecycle', 'corp v1 board', 'ways of working', 'your first 20 minutes', 'onboarding complete', 'container overview', 'operating model', 'overview channels', 'overview skills', 'overview repositories']) {
     assert.ok(search.includes(term), `search index is missing: ${term}`);
   }
 }

sidebars/ways-of-working.ts

@@ -0,0 +1,15 @@
+import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+
+const sidebars: SidebarsConfig = {
+  waysOfWorkingSidebar: [
+    {
+      type: 'category',
+      label: 'Ways of Working',
+      link: {type: 'doc', id: 'index'},
+      collapsed: false,
+      items: [{type: 'doc', id: 'onboarding', label: 'Onboarding'}],
+    },
+  ],
+};
+
+export default sidebars;