Playbook phase hub template

# ZajLibrary — authoring & site docs

You are a **ZajLibrary documentation assistant**. This is a meta page about the library itself — you help the user author or audit pages per the writing-style and component rules.

**Mission:** Help the user author or audit ZajLibrary pages per the writing-style and component rules referenced below.

## Metadata
- title: Playbook phase hub template
- url: https://library.zajapps.com/zajlibrary/authoring/content-system/resources/templates/page-templates/playbook-phase-hub/
- shelf: Resources
- doc_type: site documentation
- status: current
- kind: template
- category: zajlibrary
- subcategory: authoring
- topic: content-system
- description: Copy-paste skeleton for playbook phase index pages — phase purpose, optional diagram, Stepper, kit shortcut callout, and sub-step link list.
- tags: template, playbook, writing, build

## Authoring rules
- Help the user author or audit ZajLibrary pages per the writing-style and component rules referenced here.
- Prefer Starlight components and the visuals/warrant-test contract over raw HTML or undiagrammed walls of text.
- Cite the specific rule or section you are applying.

---

# Playbook phase hub template

## When to use

- **Shelf:** `build/playbooks/<collection>/<workstream>/0N-phase/index.mdx`
- **`kind`:** `playbook` (phase hub — not a numbered step; no `stepNumber`)
- **Diátaxis mode:** tutorial (phase-level unit within a larger journey)
- **Readers served:** readers entering one phase; agents routing to the correct step; kit users who need shortcut callouts (steps N–M)

Part of the **Playbook set (3 templates):** [overview](/zajlibrary/authoring/content-system/resources/templates/page-templates/playbook-overview/) → **phase hub** → [step](/zajlibrary/authoring/content-system/resources/templates/page-templates/playbook-step/).

## Design rationale

- **Phases are tutorial chapters** — within a Diátaxis tutorial, each chapter has its own orientation before exercises (steps); the phase hub is that chapter front matter ([Diátaxis tutorials](https://diataxis.fr/tutorials/)).
- **“Why this phase first” callout** — motivation block (`:::tip`) answers perfectionist “why can’t I skip?” without bloating every step ([learning objective upfront](https://developers.google.com/style/intro)).
- **Relationship diagram when the phase installs a system** — e.g. AI System boot flow warrants Mermaid or SVG; prose-only for multi-component phases fails the warrant test ([ZajLibrary visuals gate](/zajlibrary/authoring/content-system/resources/reference/writing-style/#visuals-are-mandatory-where-warranted)).
- **`<FileTree>` for target repo shape** — when the phase materializes files, show the end-state tree once on the hub; steps link back instead of repeating ([Google — file structure in procedures](https://developers.google.com/style/code-samples)).
- **Kit shortcut as honest partial path** — Good Docs install pattern applies to kits that shortcut steps 3–6, not the whole phase; callout must name remaining steps ([Good Docs installation guide](https://www.thegooddocsproject.dev/template/installation-guide)).
- **Numbered sub-step list at bottom** — redundant with Stepper but gives a printable, agent-parseable manifest without JavaScript.

| Section | Job | Why it's here |
| --- | --- | --- |
| Intro + `:::tip[Why…]` | Phase motivation | Tutorial chapter framing |
| What X actually is | Concept + bullet list | Explanation before procedure |
| `<FileTree>` / diagram | Structure or flow | Warrant test for relationship/process |
| Phase `<Stepper>` | Step previews in phase | Progress within phase |
| Kit shortcut callout | Optional install path | Links kit without replacing verify step |
| Sub-steps list | Plain `1.` links | Agent + print friendly |
| Committed vs gitignored table | One-time policy | Reduces repeated step prose |

## Copy-paste skeleton

Use **`.mdx`** when using `Stepper`, `FileTree`, or diagrams.

```markdown
---
title: "Phase N · &lt;Phase name&gt;"
description: One sentence — what this phase delivers and why later phases depend on it.
sidebar:
  label: Phase N overview
  order: 0
phase: "N"
category: <category>
subcategory: <workstream>
collectionOrder: N
kind: playbook
estTime: ~N min
status: current
tags: [playbook, topic]
prereqs:
  - &lt;phase or env prereq&gt;
---

&lt;Intro — what this phase does in the larger playbook.&gt;

:::tip[Why this is Phase N, not an afterthought]
&lt;2–4 sentences — risk, dependency, or speed rationale.&gt;
:::

## What "&lt;phase subject&gt;" actually is

&lt;Bullet list of artifacts / outcomes.&gt;

&lt;Optional FileTree or ```mermaid``` when structure or boot flow warrants it.&gt;

## The flow at a glance

<Stepper
  id="&lt;workstream-phase-N&gt;"
  steps={[
    { title: '&lt;Step title&gt;', body: 'One-line preview. See <a href="…">Step slug</a>.' },
    …
  ]}
/>

## Skip the typing — use the kit

&lt;Only when a kit exists for this phase.&gt;

:::note[Kit shortcut — steps X–Y]
Download the **[&lt;Kit name&gt;](/tech-stack/laravel/codecanyon/resources/kits/ai-system/)**, copy to project root, run **`seed.sh`** as an alternative through steps X–Y (after steps 1–2). Details in **[Step title](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/03-project-constitution/#alternative--kit--seedsh)**. Still finish **[Verify step](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/07-verify-and-gate/)**.
:::

➡️ **[Kit link](/tech-stack/laravel/codecanyon/resources/kits/ai-system/)** — one-line install summary.

## Sub-steps

1. [&lt;Step&gt;](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/01-project-setup/) — one-line
2. …

## &lt;Optional policy section — e.g. committed vs gitignored&gt;

| File | Committed? | Why |
| --- | --- | --- |
| … | … | … |
```

## Anti-patterns

- Do not add `stepNumber` frontmatter on the phase hub.
- Do not use `:::next` on the hub — reserve for step pages.
- Do not imply a kit replaces verify/gate steps without explicit links to them.
- Do not skip the diagram when the phase explains a multi-component boot or ownership model.

## Worked example

- [Phase 1 · Set up the AI System](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/)
- [System docs examples](/zajlibrary/authoring/content-system/resources/reference/examples/)

## Sources

- [Diátaxis — Tutorials](https://diataxis.fr/tutorials/) — phased learning units within a larger tutorial journey.
- [Good Docs Project — Installation guide template](https://www.thegooddocsproject.dev/template/installation-guide) — kit shortcut pattern (partial install path + verify elsewhere).
- [NN/g — How users read on the web](https://www.nngroup.com/articles/how-users-read-on-the-web/) — scannable sub-step lists and upfront motivation blocks.
- [Google developer documentation style guide — Procedures](https://developers.google.com/style/procedures) — phase-level orientation before numbered step procedures.
- [Writing style → Doc-type spines](/zajlibrary/authoring/content-system/resources/reference/writing-style/#doc-type-page-spines) — Playbook set (overview · phase hub · step) and kit vs playbook boundaries.

# Playbook phase hub template

> Source: https://library.zajapps.com/zajlibrary/authoring/content-system/resources/templates/page-templates/playbook-phase-hub/

## When to use

- **Shelf:** `build/playbooks/<collection>/<workstream>/0N-phase/index.mdx`
- **`kind`:** `playbook` (phase hub — not a numbered step; no `stepNumber`)
- **Diátaxis mode:** tutorial (phase-level unit within a larger journey)
- **Readers served:** readers entering one phase; agents routing to the correct step; kit users who need shortcut callouts (steps N–M)

Part of the **Playbook set (3 templates):** [overview](/zajlibrary/authoring/content-system/resources/templates/page-templates/playbook-overview/) → **phase hub** → [step](/zajlibrary/authoring/content-system/resources/templates/page-templates/playbook-step/).

## Design rationale

- **Phases are tutorial chapters** — within a Diátaxis tutorial, each chapter has its own orientation before exercises (steps); the phase hub is that chapter front matter ([Diátaxis tutorials](https://diataxis.fr/tutorials/)).
- **“Why this phase first” callout** — motivation block (`:::tip`) answers perfectionist “why can’t I skip?” without bloating every step ([learning objective upfront](https://developers.google.com/style/intro)).
- **Relationship diagram when the phase installs a system** — e.g. AI System boot flow warrants Mermaid or SVG; prose-only for multi-component phases fails the warrant test ([ZajLibrary visuals gate](/zajlibrary/authoring/content-system/resources/reference/writing-style/#visuals-are-mandatory-where-warranted)).
- **`<FileTree>` for target repo shape** — when the phase materializes files, show the end-state tree once on the hub; steps link back instead of repeating ([Google — file structure in procedures](https://developers.google.com/style/code-samples)).
- **Kit shortcut as honest partial path** — Good Docs install pattern applies to kits that shortcut steps 3–6, not the whole phase; callout must name remaining steps ([Good Docs installation guide](https://www.thegooddocsproject.dev/template/installation-guide)).
- **Numbered sub-step list at bottom** — redundant with Stepper but gives a printable, agent-parseable manifest without JavaScript.

| Section | Job | Why it's here |
| --- | --- | --- |
| Intro + `:::tip[Why…]` | Phase motivation | Tutorial chapter framing |
| What X actually is | Concept + bullet list | Explanation before procedure |
| `<FileTree>` / diagram | Structure or flow | Warrant test for relationship/process |
| Phase `<Stepper>` | Step previews in phase | Progress within phase |
| Kit shortcut callout | Optional install path | Links kit without replacing verify step |
| Sub-steps list | Plain `1.` links | Agent + print friendly |
| Committed vs gitignored table | One-time policy | Reduces repeated step prose |

## Copy-paste skeleton

Use **`.mdx`** when using `Stepper`, `FileTree`, or diagrams.

```markdown
---
title: "Phase N · &lt;Phase name&gt;"
description: One sentence — what this phase delivers and why later phases depend on it.
sidebar:
  label: Phase N overview
  order: 0
phase: "N"
category: <category>
subcategory: <workstream>
collectionOrder: N
kind: playbook
estTime: ~N min
status: current
tags: [playbook, topic]
prereqs:
  - &lt;phase or env prereq&gt;
---

&lt;Intro — what this phase does in the larger playbook.&gt;

:::tip[Why this is Phase N, not an afterthought]
&lt;2–4 sentences — risk, dependency, or speed rationale.&gt;
:::

## What "&lt;phase subject&gt;" actually is

&lt;Bullet list of artifacts / outcomes.&gt;

&lt;Optional FileTree or ```mermaid``` when structure or boot flow warrants it.&gt;

## The flow at a glance

<Stepper
  id="&lt;workstream-phase-N&gt;"
  steps={[
    { title: '&lt;Step title&gt;', body: 'One-line preview. See <a href="…">Step slug</a>.' },
    …
  ]}
/>

## Skip the typing — use the kit

&lt;Only when a kit exists for this phase.&gt;

:::note[Kit shortcut — steps X–Y]
Download the **[&lt;Kit name&gt;](/tech-stack/laravel/codecanyon/resources/kits/ai-system/)**, copy to project root, run **`seed.sh`** as an alternative through steps X–Y (after steps 1–2). Details in **[Step title](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/03-project-constitution/#alternative--kit--seedsh)**. Still finish **[Verify step](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/07-verify-and-gate/)**.
:::

➡️ **[Kit link](/tech-stack/laravel/codecanyon/resources/kits/ai-system/)** — one-line install summary.

## Sub-steps

1. [&lt;Step&gt;](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/01-project-setup/) — one-line
2. …

## &lt;Optional policy section — e.g. committed vs gitignored&gt;

| File | Committed? | Why |
| --- | --- | --- |
| … | … | … |
```

## Anti-patterns

- Do not add `stepNumber` frontmatter on the phase hub.
- Do not use `:::next` on the hub — reserve for step pages.
- Do not imply a kit replaces verify/gate steps without explicit links to them.
- Do not skip the diagram when the phase explains a multi-component boot or ownership model.

## Worked example

- [Phase 1 · Set up the AI System](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/)
- [System docs examples](/zajlibrary/authoring/content-system/resources/reference/examples/)

## Sources

- [Diátaxis — Tutorials](https://diataxis.fr/tutorials/) — phased learning units within a larger tutorial journey.
- [Good Docs Project — Installation guide template](https://www.thegooddocsproject.dev/template/installation-guide) — kit shortcut pattern (partial install path + verify elsewhere).
- [NN/g — How users read on the web](https://www.nngroup.com/articles/how-users-read-on-the-web/) — scannable sub-step lists and upfront motivation blocks.
- [Google developer documentation style guide — Procedures](https://developers.google.com/style/procedures) — phase-level orientation before numbered step procedures.
- [Writing style → Doc-type spines](/zajlibrary/authoring/content-system/resources/reference/writing-style/#doc-type-page-spines) — Playbook set (overview · phase hub · step) and kit vs playbook boundaries.

When to use

Shelf: build/playbooks/<collection>/<workstream>/0N-phase/index.mdx
kind: playbook (phase hub — not a numbered step; no stepNumber)
Diátaxis mode: tutorial (phase-level unit within a larger journey)
Readers served: readers entering one phase; agents routing to the correct step; kit users who need shortcut callouts (steps N–M)

Part of the Playbook set (3 templates): overview → phase hub → step.

Design rationale

Phases are tutorial chapters — within a Diátaxis tutorial, each chapter has its own orientation before exercises (steps); the phase hub is that chapter front matter (Diátaxis tutorials).
“Why this phase first” callout — motivation block (:::tip) answers perfectionist “why can’t I skip?” without bloating every step (learning objective upfront).
Relationship diagram when the phase installs a system — e.g. AI System boot flow warrants Mermaid or SVG; prose-only for multi-component phases fails the warrant test (ZajLibrary visuals gate).
<FileTree> for target repo shape — when the phase materializes files, show the end-state tree once on the hub; steps link back instead of repeating (Google — file structure in procedures).
Kit shortcut as honest partial path — Good Docs install pattern applies to kits that shortcut steps 3–6, not the whole phase; callout must name remaining steps (Good Docs installation guide).
Numbered sub-step list at bottom — redundant with Stepper but gives a printable, agent-parseable manifest without JavaScript.

Section	Job	Why it’s here
Intro + `:::tip[Why…]`	Phase motivation	Tutorial chapter framing
What X actually is	Concept + bullet list	Explanation before procedure
`<FileTree>` / diagram	Structure or flow	Warrant test for relationship/process
Phase `<Stepper>`	Step previews in phase	Progress within phase
Kit shortcut callout	Optional install path	Links kit without replacing verify step
Sub-steps list	Plain `1.` links	Agent + print friendly
Committed vs gitignored table	One-time policy	Reduces repeated step prose

Copy-paste skeleton

Use .mdx when using Stepper, FileTree, or diagrams.

---
title: "Phase N · &lt;Phase name&gt;"
description: One sentence — what this phase delivers and why later phases depend on it.
sidebar:
  label: Phase N overview
  order: 0
phase: "N"
category: <category>
subcategory: <workstream>
collectionOrder: N
kind: playbook
estTime: ~N min
status: current
tags: [playbook, topic]
prereqs:
  - &lt;phase or env prereq&gt;
---

import Stepper from '~/components/Stepper.astro';
import { FileTree } from '@astrojs/starlight/components';

&lt;Intro — what this phase does in the larger playbook.&gt;

:::tip[Why this is Phase N, not an afterthought]
&lt;2–4 sentences — risk, dependency, or speed rationale.&gt;
:::

## What "&lt;phase subject&gt;" actually is

&lt;Bullet list of artifacts / outcomes.&gt;

&lt;Optional FileTree or ```mermaid``` when structure or boot flow warrants it.&gt;

## The flow at a glance

<Stepper
  id="&lt;workstream-phase-N&gt;"
  steps={[
    { title: '&lt;Step title&gt;', body: 'One-line preview. See <a href="…">Step slug</a>.' },
    …
  ]}
/>

## Skip the typing — use the kit

&lt;Only when a kit exists for this phase.&gt;

:::note[Kit shortcut — steps X–Y]
Download the **[&lt;Kit name&gt;](/tech-stack/laravel/codecanyon/resources/kits/ai-system/)**, copy to project root, run **`seed.sh`** as an alternative through steps X–Y (after steps 1–2). Details in **[Step title](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/03-project-constitution/#alternative--kit--seedsh)**. Still finish **[Verify step](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/07-verify-and-gate/)**.
:::

➡️ **[Kit link](/tech-stack/laravel/codecanyon/resources/kits/ai-system/)** — one-line install summary.

## Sub-steps

1. [&lt;Step&gt;](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/01-project-setup/) — one-line
2. …

## &lt;Optional policy section — e.g. committed vs gitignored&gt;

| File | Committed? | Why |
| --- | --- | --- |
| … | … | … |

Anti-patterns

Do not add stepNumber frontmatter on the phase hub.
Do not use :::next on the hub — reserve for step pages.
Do not imply a kit replaces verify/gate steps without explicit links to them.
Do not skip the diagram when the phase explains a multi-component boot or ownership model.

Worked example

Sources

Diátaxis — Tutorials — phased learning units within a larger tutorial journey.
Good Docs Project — Installation guide template — kit shortcut pattern (partial install path + verify elsewhere).
NN/g — How users read on the web — scannable sub-step lists and upfront motivation blocks.
Google developer documentation style guide — Procedures — phase-level orientation before numbered step procedures.
Writing style → Doc-type spines — Playbook set (overview · phase hub · step) and kit vs playbook boundaries.

# ZajLibrary — authoring & site docs

You are a **ZajLibrary documentation assistant**. This is a meta page about the library itself — you help the user author or audit pages per the writing-style and component rules.

**Mission:** Help the user author or audit ZajLibrary pages per the writing-style and component rules referenced below.

## Metadata
- title: Playbook phase hub template
- url: https://library.zajapps.com/zajlibrary/authoring/content-system/resources/templates/page-templates/playbook-phase-hub/
- shelf: Resources
- doc_type: site documentation
- status: current
- kind: template
- category: zajlibrary
- subcategory: authoring
- topic: content-system
- description: Copy-paste skeleton for playbook phase index pages — phase purpose, optional diagram, Stepper, kit shortcut callout, and sub-step link list.
- tags: template, playbook, writing, build

## Authoring rules
- Help the user author or audit ZajLibrary pages per the writing-style and component rules referenced here.
- Prefer Starlight components and the visuals/warrant-test contract over raw HTML or undiagrammed walls of text.
- Cite the specific rule or section you are applying.

---

# Playbook phase hub template

## When to use

- **Shelf:** `build/playbooks/<collection>/<workstream>/0N-phase/index.mdx`
- **`kind`:** `playbook` (phase hub — not a numbered step; no `stepNumber`)
- **Diátaxis mode:** tutorial (phase-level unit within a larger journey)
- **Readers served:** readers entering one phase; agents routing to the correct step; kit users who need shortcut callouts (steps N–M)

Part of the **Playbook set (3 templates):** [overview](/zajlibrary/authoring/content-system/resources/templates/page-templates/playbook-overview/) → **phase hub** → [step](/zajlibrary/authoring/content-system/resources/templates/page-templates/playbook-step/).

## Design rationale

- **Phases are tutorial chapters** — within a Diátaxis tutorial, each chapter has its own orientation before exercises (steps); the phase hub is that chapter front matter ([Diátaxis tutorials](https://diataxis.fr/tutorials/)).
- **“Why this phase first” callout** — motivation block (`:::tip`) answers perfectionist “why can’t I skip?” without bloating every step ([learning objective upfront](https://developers.google.com/style/intro)).
- **Relationship diagram when the phase installs a system** — e.g. AI System boot flow warrants Mermaid or SVG; prose-only for multi-component phases fails the warrant test ([ZajLibrary visuals gate](/zajlibrary/authoring/content-system/resources/reference/writing-style/#visuals-are-mandatory-where-warranted)).
- **`<FileTree>` for target repo shape** — when the phase materializes files, show the end-state tree once on the hub; steps link back instead of repeating ([Google — file structure in procedures](https://developers.google.com/style/code-samples)).
- **Kit shortcut as honest partial path** — Good Docs install pattern applies to kits that shortcut steps 3–6, not the whole phase; callout must name remaining steps ([Good Docs installation guide](https://www.thegooddocsproject.dev/template/installation-guide)).
- **Numbered sub-step list at bottom** — redundant with Stepper but gives a printable, agent-parseable manifest without JavaScript.

| Section | Job | Why it's here |
| --- | --- | --- |
| Intro + `:::tip[Why…]` | Phase motivation | Tutorial chapter framing |
| What X actually is | Concept + bullet list | Explanation before procedure |
| `<FileTree>` / diagram | Structure or flow | Warrant test for relationship/process |
| Phase `<Stepper>` | Step previews in phase | Progress within phase |
| Kit shortcut callout | Optional install path | Links kit without replacing verify step |
| Sub-steps list | Plain `1.` links | Agent + print friendly |
| Committed vs gitignored table | One-time policy | Reduces repeated step prose |

## Copy-paste skeleton

Use **`.mdx`** when using `Stepper`, `FileTree`, or diagrams.

```markdown
---
title: "Phase N · &lt;Phase name&gt;"
description: One sentence — what this phase delivers and why later phases depend on it.
sidebar:
  label: Phase N overview
  order: 0
phase: "N"
category: <category>
subcategory: <workstream>
collectionOrder: N
kind: playbook
estTime: ~N min
status: current
tags: [playbook, topic]
prereqs:
  - &lt;phase or env prereq&gt;
---

&lt;Intro — what this phase does in the larger playbook.&gt;

:::tip[Why this is Phase N, not an afterthought]
&lt;2–4 sentences — risk, dependency, or speed rationale.&gt;
:::

## What "&lt;phase subject&gt;" actually is

&lt;Bullet list of artifacts / outcomes.&gt;

&lt;Optional FileTree or ```mermaid``` when structure or boot flow warrants it.&gt;

## The flow at a glance

<Stepper
  id="&lt;workstream-phase-N&gt;"
  steps={[
    { title: '&lt;Step title&gt;', body: 'One-line preview. See <a href="…">Step slug</a>.' },
    …
  ]}
/>

## Skip the typing — use the kit

&lt;Only when a kit exists for this phase.&gt;

:::note[Kit shortcut — steps X–Y]
Download the **[&lt;Kit name&gt;](/tech-stack/laravel/codecanyon/resources/kits/ai-system/)**, copy to project root, run **`seed.sh`** as an alternative through steps X–Y (after steps 1–2). Details in **[Step title](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/03-project-constitution/#alternative--kit--seedsh)**. Still finish **[Verify step](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/07-verify-and-gate/)**.
:::

➡️ **[Kit link](/tech-stack/laravel/codecanyon/resources/kits/ai-system/)** — one-line install summary.

## Sub-steps

1. [&lt;Step&gt;](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/01-project-setup/) — one-line
2. …

## &lt;Optional policy section — e.g. committed vs gitignored&gt;

| File | Committed? | Why |
| --- | --- | --- |
| … | … | … |
```

## Anti-patterns

- Do not add `stepNumber` frontmatter on the phase hub.
- Do not use `:::next` on the hub — reserve for step pages.
- Do not imply a kit replaces verify/gate steps without explicit links to them.
- Do not skip the diagram when the phase explains a multi-component boot or ownership model.

## Worked example

- [Phase 1 · Set up the AI System](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/)
- [System docs examples](/zajlibrary/authoring/content-system/resources/reference/examples/)

## Sources

- [Diátaxis — Tutorials](https://diataxis.fr/tutorials/) — phased learning units within a larger tutorial journey.
- [Good Docs Project — Installation guide template](https://www.thegooddocsproject.dev/template/installation-guide) — kit shortcut pattern (partial install path + verify elsewhere).
- [NN/g — How users read on the web](https://www.nngroup.com/articles/how-users-read-on-the-web/) — scannable sub-step lists and upfront motivation blocks.
- [Google developer documentation style guide — Procedures](https://developers.google.com/style/procedures) — phase-level orientation before numbered step procedures.
- [Writing style → Doc-type spines](/zajlibrary/authoring/content-system/resources/reference/writing-style/#doc-type-page-spines) — Playbook set (overview · phase hub · step) and kit vs playbook boundaries.

# Playbook phase hub template

> Source: https://library.zajapps.com/zajlibrary/authoring/content-system/resources/templates/page-templates/playbook-phase-hub/

## When to use

- **Shelf:** `build/playbooks/<collection>/<workstream>/0N-phase/index.mdx`
- **`kind`:** `playbook` (phase hub — not a numbered step; no `stepNumber`)
- **Diátaxis mode:** tutorial (phase-level unit within a larger journey)
- **Readers served:** readers entering one phase; agents routing to the correct step; kit users who need shortcut callouts (steps N–M)

Part of the **Playbook set (3 templates):** [overview](/zajlibrary/authoring/content-system/resources/templates/page-templates/playbook-overview/) → **phase hub** → [step](/zajlibrary/authoring/content-system/resources/templates/page-templates/playbook-step/).

## Design rationale

- **Phases are tutorial chapters** — within a Diátaxis tutorial, each chapter has its own orientation before exercises (steps); the phase hub is that chapter front matter ([Diátaxis tutorials](https://diataxis.fr/tutorials/)).
- **“Why this phase first” callout** — motivation block (`:::tip`) answers perfectionist “why can’t I skip?” without bloating every step ([learning objective upfront](https://developers.google.com/style/intro)).
- **Relationship diagram when the phase installs a system** — e.g. AI System boot flow warrants Mermaid or SVG; prose-only for multi-component phases fails the warrant test ([ZajLibrary visuals gate](/zajlibrary/authoring/content-system/resources/reference/writing-style/#visuals-are-mandatory-where-warranted)).
- **`<FileTree>` for target repo shape** — when the phase materializes files, show the end-state tree once on the hub; steps link back instead of repeating ([Google — file structure in procedures](https://developers.google.com/style/code-samples)).
- **Kit shortcut as honest partial path** — Good Docs install pattern applies to kits that shortcut steps 3–6, not the whole phase; callout must name remaining steps ([Good Docs installation guide](https://www.thegooddocsproject.dev/template/installation-guide)).
- **Numbered sub-step list at bottom** — redundant with Stepper but gives a printable, agent-parseable manifest without JavaScript.

| Section | Job | Why it's here |
| --- | --- | --- |
| Intro + `:::tip[Why…]` | Phase motivation | Tutorial chapter framing |
| What X actually is | Concept + bullet list | Explanation before procedure |
| `<FileTree>` / diagram | Structure or flow | Warrant test for relationship/process |
| Phase `<Stepper>` | Step previews in phase | Progress within phase |
| Kit shortcut callout | Optional install path | Links kit without replacing verify step |
| Sub-steps list | Plain `1.` links | Agent + print friendly |
| Committed vs gitignored table | One-time policy | Reduces repeated step prose |

## Copy-paste skeleton

Use **`.mdx`** when using `Stepper`, `FileTree`, or diagrams.

```markdown
---
title: "Phase N · &lt;Phase name&gt;"
description: One sentence — what this phase delivers and why later phases depend on it.
sidebar:
  label: Phase N overview
  order: 0
phase: "N"
category: <category>
subcategory: <workstream>
collectionOrder: N
kind: playbook
estTime: ~N min
status: current
tags: [playbook, topic]
prereqs:
  - &lt;phase or env prereq&gt;
---

&lt;Intro — what this phase does in the larger playbook.&gt;

:::tip[Why this is Phase N, not an afterthought]
&lt;2–4 sentences — risk, dependency, or speed rationale.&gt;
:::

## What "&lt;phase subject&gt;" actually is

&lt;Bullet list of artifacts / outcomes.&gt;

&lt;Optional FileTree or ```mermaid``` when structure or boot flow warrants it.&gt;

## The flow at a glance

<Stepper
  id="&lt;workstream-phase-N&gt;"
  steps={[
    { title: '&lt;Step title&gt;', body: 'One-line preview. See <a href="…">Step slug</a>.' },
    …
  ]}
/>

## Skip the typing — use the kit

&lt;Only when a kit exists for this phase.&gt;

:::note[Kit shortcut — steps X–Y]
Download the **[&lt;Kit name&gt;](/tech-stack/laravel/codecanyon/resources/kits/ai-system/)**, copy to project root, run **`seed.sh`** as an alternative through steps X–Y (after steps 1–2). Details in **[Step title](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/03-project-constitution/#alternative--kit--seedsh)**. Still finish **[Verify step](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/07-verify-and-gate/)**.
:::

➡️ **[Kit link](/tech-stack/laravel/codecanyon/resources/kits/ai-system/)** — one-line install summary.

## Sub-steps

1. [&lt;Step&gt;](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/01-project-setup/) — one-line
2. …

## &lt;Optional policy section — e.g. committed vs gitignored&gt;

| File | Committed? | Why |
| --- | --- | --- |
| … | … | … |
```

## Anti-patterns

- Do not add `stepNumber` frontmatter on the phase hub.
- Do not use `:::next` on the hub — reserve for step pages.
- Do not imply a kit replaces verify/gate steps without explicit links to them.
- Do not skip the diagram when the phase explains a multi-component boot or ownership model.

## Worked example

- [Phase 1 · Set up the AI System](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/)
- [System docs examples](/zajlibrary/authoring/content-system/resources/reference/examples/)

## Sources

- [Diátaxis — Tutorials](https://diataxis.fr/tutorials/) — phased learning units within a larger tutorial journey.
- [Good Docs Project — Installation guide template](https://www.thegooddocsproject.dev/template/installation-guide) — kit shortcut pattern (partial install path + verify elsewhere).
- [NN/g — How users read on the web](https://www.nngroup.com/articles/how-users-read-on-the-web/) — scannable sub-step lists and upfront motivation blocks.
- [Google developer documentation style guide — Procedures](https://developers.google.com/style/procedures) — phase-level orientation before numbered step procedures.
- [Writing style → Doc-type spines](/zajlibrary/authoring/content-system/resources/reference/writing-style/#doc-type-page-spines) — Playbook set (overview · phase hub · step) and kit vs playbook boundaries.