Path layout

# 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: Path layout
- url: https://library.zajapps.com/zajlibrary/authoring/content-system/resources/reference/content-architecture/path-layout/
- shelf: Resources
- doc_type: site documentation
- status: current
- kind: reference
- collection: zajlibrary-authoring
- category: zajlibrary
- subcategory: authoring
- topic: content-system
- description: Where files live in the topic-first tree — category, subcategory, topic, then shelf and kind.
- tags: system-docs, paths, taxonomy, sidebar

## 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.

---

# Path layout

Use this **after** the [decision tree](/zajlibrary/authoring/content-system/resources/reference/content-architecture/decision-tree/) picks shelf + kind. Physical paths and frontmatter must agree so sidebars, `/browse/`, `/categories/`, `/subcategories/`, tags, search, and MCP stay in sync.

## The rule

Leaf pages (anything that is not a type hub) live at:

```txt
app/src/content/docs/<category>/<subcategory>/<topic>/<shelf>/<kind>/<slug>.md(x)
```

| Segment | Source | Example |
| --- | --- | --- |
| `<category>` | Frontmatter `category` (slug) | `tech-stack`, `ai-systems` |
| `<subcategory>` | Frontmatter `subcategory` (slug) | `laravel`, `integrations` |
| `<topic>` | Frontmatter `topic` (slug) | `codecanyon`, `ai-agent-integration` |
| `<shelf>` | Reader intent | `learn`, `build`, `resources` |
| `<kind>` | Content type folder | `guides`, `playbooks`, `templates` |
| `<slug>` | Descriptive filename | `build-an-mcp-server.mdx` |

Topic, category, and subcategory hubs may use `index.md(x)` at their own folder level. `_meta.yaml` may sit beside any folder to tune the generated sidebar. Do not drop loose pages directly under a shelf or kind without the subject path.

Frontmatter must match the path (lowercase slugs):

```yaml
kind: guide
collection: ai-agent-integration   # optional metadata; not an active route family
category: ai-systems
subcategory: integrations
topic: ai-agent-integration
tags: [mcp, astro, vercel]
```

Generated browse routes still come from frontmatter and the path: `/browse/`, `/categories/ai-systems/`, `/subcategories/integrations/`, and `/tags/<tag>/`.

## Examples

| Page | Path |
| --- | --- |
| Build an MCP server | `ai-systems/integrations/ai-agent-integration/learn/guides/mcp/build-an-mcp-server.mdx` |
| Create a Claude Code plugin | `ai-systems/integrations/ai-agent-integration/learn/guides/claude-code/create-a-claude-code-plugin.mdx` |
| Laravel deployment concepts | `tech-stack/laravel/codecanyon/learn/guides/deployment-concepts.mdx` |

Hub pages use `index.mdx` at the relevant level, for example `tech-stack/laravel/codecanyon/index.mdx` for the topic hub or `tech-stack/laravel/codecanyon/learn/guides/index.mdx` for a guide hub.

## Workflow exception (Build shelf)

Multi-phase **playbooks** and **runbooks** may add workflow segments **after** shelf + kind:

```txt
tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/01-dependencies-assets.mdx
```

Here `setup-new` is the workflow root **after** shelf + kind. Those pages still carry `category`, `subcategory`, and `topic` in frontmatter for Browse, search, MCP, and prompt metadata.

## Sidebar and `_meta.yaml`

- Starlight autogenerates sidebar groups from folders.
- Tune labels with `_meta.yaml` at each folder level (`label`, `collapsed`, `order`).
- After any move: run the path audit and `npm run build` (link validator catches stale URLs).

```bash
# From repo root
python3 scripts/content-path-audit.py
cd app && npm run build
```

## Migration checklist (every intake or refactor)

1. **Path** — file under `<category>/<subcategory>/<topic>/<shelf>/<kind>/`, not flat under `<shelf>/<kind>/`.
2. **Frontmatter** — `category`, `subcategory`, `topic`, `collection`, `tags`, `kind` filled where relevant; slugs match folders.
3. **Links** — grep for old URL prefixes and update every internal link to the canonical path (redirects are off).
4. **Sidebar** — add/update `_meta.yaml` for new folder labels.
5. **Taxonomy pages** — spot-check `/browse/`, `/categories/`, `/subcategories/`, and `/tags/` for the item.
6. **Build** — `cd app && npm run build` (link validator + Pagefind).

## Known follow-ups

**`build/blueprints/`** and **`build/sops/`** — some topics still only have type hubs. First leaf blueprints/SOPs should land under the topic-first rule above.

# Path layout

> Source: https://library.zajapps.com/zajlibrary/authoring/content-system/resources/reference/content-architecture/path-layout/

Use this **after** the [decision tree](/zajlibrary/authoring/content-system/resources/reference/content-architecture/decision-tree/) picks shelf + kind. Physical paths and frontmatter must agree so sidebars, `/browse/`, `/categories/`, `/subcategories/`, tags, search, and MCP stay in sync.

## The rule

Leaf pages (anything that is not a type hub) live at:

```txt
app/src/content/docs/<category>/<subcategory>/<topic>/<shelf>/<kind>/<slug>.md(x)
```

| Segment | Source | Example |
| --- | --- | --- |
| `<category>` | Frontmatter `category` (slug) | `tech-stack`, `ai-systems` |
| `<subcategory>` | Frontmatter `subcategory` (slug) | `laravel`, `integrations` |
| `<topic>` | Frontmatter `topic` (slug) | `codecanyon`, `ai-agent-integration` |
| `<shelf>` | Reader intent | `learn`, `build`, `resources` |
| `<kind>` | Content type folder | `guides`, `playbooks`, `templates` |
| `<slug>` | Descriptive filename | `build-an-mcp-server.mdx` |

Topic, category, and subcategory hubs may use `index.md(x)` at their own folder level. `_meta.yaml` may sit beside any folder to tune the generated sidebar. Do not drop loose pages directly under a shelf or kind without the subject path.

Frontmatter must match the path (lowercase slugs):

```yaml
kind: guide
collection: ai-agent-integration   # optional metadata; not an active route family
category: ai-systems
subcategory: integrations
topic: ai-agent-integration
tags: [mcp, astro, vercel]
```

Generated browse routes still come from frontmatter and the path: `/browse/`, `/categories/ai-systems/`, `/subcategories/integrations/`, and `/tags/<tag>/`.

## Examples

| Page | Path |
| --- | --- |
| Build an MCP server | `ai-systems/integrations/ai-agent-integration/learn/guides/mcp/build-an-mcp-server.mdx` |
| Create a Claude Code plugin | `ai-systems/integrations/ai-agent-integration/learn/guides/claude-code/create-a-claude-code-plugin.mdx` |
| Laravel deployment concepts | `tech-stack/laravel/codecanyon/learn/guides/deployment-concepts.mdx` |

Hub pages use `index.mdx` at the relevant level, for example `tech-stack/laravel/codecanyon/index.mdx` for the topic hub or `tech-stack/laravel/codecanyon/learn/guides/index.mdx` for a guide hub.

## Workflow exception (Build shelf)

Multi-phase **playbooks** and **runbooks** may add workflow segments **after** shelf + kind:

```txt
tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/01-dependencies-assets.mdx
```

Here `setup-new` is the workflow root **after** shelf + kind. Those pages still carry `category`, `subcategory`, and `topic` in frontmatter for Browse, search, MCP, and prompt metadata.

## Sidebar and `_meta.yaml`

- Starlight autogenerates sidebar groups from folders.
- Tune labels with `_meta.yaml` at each folder level (`label`, `collapsed`, `order`).
- After any move: run the path audit and `npm run build` (link validator catches stale URLs).

```bash
# From repo root
python3 scripts/content-path-audit.py
cd app && npm run build
```

## Migration checklist (every intake or refactor)

1. **Path** — file under `<category>/<subcategory>/<topic>/<shelf>/<kind>/`, not flat under `<shelf>/<kind>/`.
2. **Frontmatter** — `category`, `subcategory`, `topic`, `collection`, `tags`, `kind` filled where relevant; slugs match folders.
3. **Links** — grep for old URL prefixes and update every internal link to the canonical path (redirects are off).
4. **Sidebar** — add/update `_meta.yaml` for new folder labels.
5. **Taxonomy pages** — spot-check `/browse/`, `/categories/`, `/subcategories/`, and `/tags/` for the item.
6. **Build** — `cd app && npm run build` (link validator + Pagefind).

## Known follow-ups

**`build/blueprints/`** and **`build/sops/`** — some topics still only have type hubs. First leaf blueprints/SOPs should land under the topic-first rule above.

Use this after the decision tree picks shelf + kind. Physical paths and frontmatter must agree so sidebars, /browse/, /categories/, /subcategories/, tags, search, and MCP stay in sync.

The rule

Leaf pages (anything that is not a type hub) live at:

app/src/content/docs/<category>/<subcategory>/<topic>/<shelf>/<kind>/<slug>.md(x)

Segment	Source	Example
`<category>`	Frontmatter `category` (slug)	`tech-stack`, `ai-systems`
`<subcategory>`	Frontmatter `subcategory` (slug)	`laravel`, `integrations`
`<topic>`	Frontmatter `topic` (slug)	`codecanyon`, `ai-agent-integration`
`<shelf>`	Reader intent	`learn`, `build`, `resources`
`<kind>`	Content type folder	`guides`, `playbooks`, `templates`
`<slug>`	Descriptive filename	`build-an-mcp-server.mdx`

Topic, category, and subcategory hubs may use index.md(x) at their own folder level. _meta.yaml may sit beside any folder to tune the generated sidebar. Do not drop loose pages directly under a shelf or kind without the subject path.

Frontmatter must match the path (lowercase slugs):

kind: guide
collection: ai-agent-integration   # optional metadata; not an active route family
category: ai-systems
subcategory: integrations
topic: ai-agent-integration
tags: [mcp, astro, vercel]

Generated browse routes still come from frontmatter and the path: /browse/, /categories/ai-systems/, /subcategories/integrations/, and /tags/<tag>/.

Examples

Page	Path
Build an MCP server	`ai-systems/integrations/ai-agent-integration/learn/guides/mcp/build-an-mcp-server.mdx`
Create a Claude Code plugin	`ai-systems/integrations/ai-agent-integration/learn/guides/claude-code/create-a-claude-code-plugin.mdx`
Laravel deployment concepts	`tech-stack/laravel/codecanyon/learn/guides/deployment-concepts.mdx`

Hub pages use index.mdx at the relevant level, for example tech-stack/laravel/codecanyon/index.mdx for the topic hub or tech-stack/laravel/codecanyon/learn/guides/index.mdx for a guide hub.

Workflow exception (Build shelf)

Multi-phase playbooks and runbooks may add workflow segments after shelf + kind:

tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/01-dependencies-assets.mdx

Here setup-new is the workflow root after shelf + kind. Those pages still carry category, subcategory, and topic in frontmatter for Browse, search, MCP, and prompt metadata.

Sidebar and `_meta.yaml`

Starlight autogenerates sidebar groups from folders.
Tune labels with _meta.yaml at each folder level (label, collapsed, order).
After any move: run the path audit and npm run build (link validator catches stale URLs).

# From repo root
python3 scripts/content-path-audit.py
cd app && npm run build

Migration checklist (every intake or refactor)

Path — file under <category>/<subcategory>/<topic>/<shelf>/<kind>/, not flat under <shelf>/<kind>/.
Frontmatter — category, subcategory, topic, collection, tags, kind filled where relevant; slugs match folders.
Links — grep for old URL prefixes and update every internal link to the canonical path (redirects are off).
Sidebar — add/update _meta.yaml for new folder labels.
Taxonomy pages — spot-check /browse/, /categories/, /subcategories/, and /tags/ for the item.
Build — cd app && npm run build (link validator + Pagefind).

Known follow-ups

build/blueprints/ and build/sops/ — some topics still only have type hubs. First leaf blueprints/SOPs should land under the topic-first rule above.

# 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: Path layout
- url: https://library.zajapps.com/zajlibrary/authoring/content-system/resources/reference/content-architecture/path-layout/
- shelf: Resources
- doc_type: site documentation
- status: current
- kind: reference
- collection: zajlibrary-authoring
- category: zajlibrary
- subcategory: authoring
- topic: content-system
- description: Where files live in the topic-first tree — category, subcategory, topic, then shelf and kind.
- tags: system-docs, paths, taxonomy, sidebar

## 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.

---

# Path layout

Use this **after** the [decision tree](/zajlibrary/authoring/content-system/resources/reference/content-architecture/decision-tree/) picks shelf + kind. Physical paths and frontmatter must agree so sidebars, `/browse/`, `/categories/`, `/subcategories/`, tags, search, and MCP stay in sync.

## The rule

Leaf pages (anything that is not a type hub) live at:

```txt
app/src/content/docs/<category>/<subcategory>/<topic>/<shelf>/<kind>/<slug>.md(x)
```

| Segment | Source | Example |
| --- | --- | --- |
| `<category>` | Frontmatter `category` (slug) | `tech-stack`, `ai-systems` |
| `<subcategory>` | Frontmatter `subcategory` (slug) | `laravel`, `integrations` |
| `<topic>` | Frontmatter `topic` (slug) | `codecanyon`, `ai-agent-integration` |
| `<shelf>` | Reader intent | `learn`, `build`, `resources` |
| `<kind>` | Content type folder | `guides`, `playbooks`, `templates` |
| `<slug>` | Descriptive filename | `build-an-mcp-server.mdx` |

Topic, category, and subcategory hubs may use `index.md(x)` at their own folder level. `_meta.yaml` may sit beside any folder to tune the generated sidebar. Do not drop loose pages directly under a shelf or kind without the subject path.

Frontmatter must match the path (lowercase slugs):

```yaml
kind: guide
collection: ai-agent-integration   # optional metadata; not an active route family
category: ai-systems
subcategory: integrations
topic: ai-agent-integration
tags: [mcp, astro, vercel]
```

Generated browse routes still come from frontmatter and the path: `/browse/`, `/categories/ai-systems/`, `/subcategories/integrations/`, and `/tags/<tag>/`.

## Examples

| Page | Path |
| --- | --- |
| Build an MCP server | `ai-systems/integrations/ai-agent-integration/learn/guides/mcp/build-an-mcp-server.mdx` |
| Create a Claude Code plugin | `ai-systems/integrations/ai-agent-integration/learn/guides/claude-code/create-a-claude-code-plugin.mdx` |
| Laravel deployment concepts | `tech-stack/laravel/codecanyon/learn/guides/deployment-concepts.mdx` |

Hub pages use `index.mdx` at the relevant level, for example `tech-stack/laravel/codecanyon/index.mdx` for the topic hub or `tech-stack/laravel/codecanyon/learn/guides/index.mdx` for a guide hub.

## Workflow exception (Build shelf)

Multi-phase **playbooks** and **runbooks** may add workflow segments **after** shelf + kind:

```txt
tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/01-dependencies-assets.mdx
```

Here `setup-new` is the workflow root **after** shelf + kind. Those pages still carry `category`, `subcategory`, and `topic` in frontmatter for Browse, search, MCP, and prompt metadata.

## Sidebar and `_meta.yaml`

- Starlight autogenerates sidebar groups from folders.
- Tune labels with `_meta.yaml` at each folder level (`label`, `collapsed`, `order`).
- After any move: run the path audit and `npm run build` (link validator catches stale URLs).

```bash
# From repo root
python3 scripts/content-path-audit.py
cd app && npm run build
```

## Migration checklist (every intake or refactor)

1. **Path** — file under `<category>/<subcategory>/<topic>/<shelf>/<kind>/`, not flat under `<shelf>/<kind>/`.
2. **Frontmatter** — `category`, `subcategory`, `topic`, `collection`, `tags`, `kind` filled where relevant; slugs match folders.
3. **Links** — grep for old URL prefixes and update every internal link to the canonical path (redirects are off).
4. **Sidebar** — add/update `_meta.yaml` for new folder labels.
5. **Taxonomy pages** — spot-check `/browse/`, `/categories/`, `/subcategories/`, and `/tags/` for the item.
6. **Build** — `cd app && npm run build` (link validator + Pagefind).

## Known follow-ups

**`build/blueprints/`** and **`build/sops/`** — some topics still only have type hubs. First leaf blueprints/SOPs should land under the topic-first rule above.

# Path layout

> Source: https://library.zajapps.com/zajlibrary/authoring/content-system/resources/reference/content-architecture/path-layout/

Use this **after** the [decision tree](/zajlibrary/authoring/content-system/resources/reference/content-architecture/decision-tree/) picks shelf + kind. Physical paths and frontmatter must agree so sidebars, `/browse/`, `/categories/`, `/subcategories/`, tags, search, and MCP stay in sync.

## The rule

Leaf pages (anything that is not a type hub) live at:

```txt
app/src/content/docs/<category>/<subcategory>/<topic>/<shelf>/<kind>/<slug>.md(x)
```

| Segment | Source | Example |
| --- | --- | --- |
| `<category>` | Frontmatter `category` (slug) | `tech-stack`, `ai-systems` |
| `<subcategory>` | Frontmatter `subcategory` (slug) | `laravel`, `integrations` |
| `<topic>` | Frontmatter `topic` (slug) | `codecanyon`, `ai-agent-integration` |
| `<shelf>` | Reader intent | `learn`, `build`, `resources` |
| `<kind>` | Content type folder | `guides`, `playbooks`, `templates` |
| `<slug>` | Descriptive filename | `build-an-mcp-server.mdx` |

Topic, category, and subcategory hubs may use `index.md(x)` at their own folder level. `_meta.yaml` may sit beside any folder to tune the generated sidebar. Do not drop loose pages directly under a shelf or kind without the subject path.

Frontmatter must match the path (lowercase slugs):

```yaml
kind: guide
collection: ai-agent-integration   # optional metadata; not an active route family
category: ai-systems
subcategory: integrations
topic: ai-agent-integration
tags: [mcp, astro, vercel]
```

Generated browse routes still come from frontmatter and the path: `/browse/`, `/categories/ai-systems/`, `/subcategories/integrations/`, and `/tags/<tag>/`.

## Examples

| Page | Path |
| --- | --- |
| Build an MCP server | `ai-systems/integrations/ai-agent-integration/learn/guides/mcp/build-an-mcp-server.mdx` |
| Create a Claude Code plugin | `ai-systems/integrations/ai-agent-integration/learn/guides/claude-code/create-a-claude-code-plugin.mdx` |
| Laravel deployment concepts | `tech-stack/laravel/codecanyon/learn/guides/deployment-concepts.mdx` |

Hub pages use `index.mdx` at the relevant level, for example `tech-stack/laravel/codecanyon/index.mdx` for the topic hub or `tech-stack/laravel/codecanyon/learn/guides/index.mdx` for a guide hub.

## Workflow exception (Build shelf)

Multi-phase **playbooks** and **runbooks** may add workflow segments **after** shelf + kind:

```txt
tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/01-dependencies-assets.mdx
```

Here `setup-new` is the workflow root **after** shelf + kind. Those pages still carry `category`, `subcategory`, and `topic` in frontmatter for Browse, search, MCP, and prompt metadata.

## Sidebar and `_meta.yaml`

- Starlight autogenerates sidebar groups from folders.
- Tune labels with `_meta.yaml` at each folder level (`label`, `collapsed`, `order`).
- After any move: run the path audit and `npm run build` (link validator catches stale URLs).

```bash
# From repo root
python3 scripts/content-path-audit.py
cd app && npm run build
```

## Migration checklist (every intake or refactor)

1. **Path** — file under `<category>/<subcategory>/<topic>/<shelf>/<kind>/`, not flat under `<shelf>/<kind>/`.
2. **Frontmatter** — `category`, `subcategory`, `topic`, `collection`, `tags`, `kind` filled where relevant; slugs match folders.
3. **Links** — grep for old URL prefixes and update every internal link to the canonical path (redirects are off).
4. **Sidebar** — add/update `_meta.yaml` for new folder labels.
5. **Taxonomy pages** — spot-check `/browse/`, `/categories/`, `/subcategories/`, and `/tags/` for the item.
6. **Build** — `cd app && npm run build` (link validator + Pagefind).

## Known follow-ups

**`build/blueprints/`** and **`build/sops/`** — some topics still only have type hubs. First leaf blueprints/SOPs should land under the topic-first rule above.