# Creating and Organizing Briefs

This Brief explains how to create Briefs and organize knowledge across them. You (the AI
agent) are usually the one doing the creating, on the user's behalf. Read this as
operational guidance for that work.

## The core shift: organize knowledge, don't write a document

A Brief is not a document. Documents are crafted by a human to be read by a human — they
cover an entire subject across many sections and pages, with narrative and transitions to
carry a reader through. A Brief is hosted context that empowers an AI agent. The unit is a
scoped block of knowledge, not a whole subject.

So creating Briefs is not "write one big Brief about X." It is "organize the user's
knowledge into a set of well-scoped Briefs that reference each other." Think of a
well-structured documentation site (e.g. Tailwind CSS) where each page holds complete
knowledge about one scoped topic — theme, spacing, color — rather than one sprawling page
covering everything.

## Scope each Brief tightly

- One Brief = one coherent block of knowledge a reader would want to pull as a unit.
- Prefer several focused Briefs over one large one. If a Brief is growing sections that
  each stand on their own, split them out.
- A design system is not one Brief. It's an index Brief that gives the overview and links
  to child Briefs: theme, spacing, color tokens, typography, accessibility, etc.

## Use an index Brief to tie things together

For any multi-part subject, create an index (or hub) Brief that:

- Gives a short overview of the whole subject.
- Links to the child Briefs by URL, with a one-line description of what each covers.
- Lets a reading agent decide which child Briefs it actually needs to fetch for the
  question at hand, instead of loading everything.

Child Briefs can link back to the index and across to siblings where it helps the agent
navigate. Links are how an agent discovers what else is worth fetching.

## What a Brief can contain

Briefs are just markdown, so a Brief can hold more than facts:

- Knowledge and context (the subject matter itself).
- Instructions to the reading agent on how to use the Brief or how to guide the user.
- References/links to other Briefs so the agent can fetch more context when needed.
- Freshness guidance — e.g. "re-fetch this before relying on pricing."

## Naming

- You (the agent) may name Briefs yourself. Briefs are AI-native, so it's usually
  preferred to let the agent choose clear, consistent names rather than asking the user to.
- Use short, descriptive, URL-friendly names (`design-system`, `color-tokens`,
  `onboarding-index`). Names appear in the URL, so keep them stable once shared.
- The user can still name a Brief explicitly when they care about the exact slug.

## Where to create

- Personal Briefs are created under the user's own namespace by default.
- Org Briefs are created under an org namespace and inherit org access/permissions — use
  these when knowledge belongs to a team rather than one person.

## Practical workflow for the agent

1. Understand the knowledge the user wants to capture and how it will be queried.
2. Decide the structure: a single Brief if truly atomic, otherwise an index plus children.
3. Create each Brief with a clear scope and name; cross-link them.
4. Hand the user the relevant URL(s). Because Briefs are hosted, the URL stays stable —
   update the content in place over time instead of creating new versions.

## The point

Briefs remove the hassle of authoring documents. A document is a human artifact made to be
read; a Brief lets a user share knowledge or guidance easily and lets their AI agent handle
organizing and maintaining it. When in doubt, take the burden off the user: structure,
name, and link the Briefs for them.