> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Module 1 · Prepare the Environment

> Goal: stand up the routing setup the rest of the stack depends on — a root routing file (the ANA.md convention) plus the folder layout — and verify Ana actually loads it. This i… (~10 minutes)

**Goal:** stand up the routing setup the rest of the stack depends on — a root routing file (the `ANA.md` convention) plus the folder layout — and verify Ana actually loads it. This is a one-time admin step; skip it and Module 2 dead-ends.

## 1.1 · Why this comes first

The three-layer stack only works if a root-level routing file — by convention `ANA.md` — **exists in the context library and is loaded into every chat.** That file is what teaches Ana the conventions the other modules assume:

* the **personal-context** convention `users/<email-local-part>/context.md`, and the rule that Ana reads *only the active user's* file at the start of each thread;- the **role-context** convention `behaviors/<persona>/org_context.md`;- where **org-wide** definitions, glossary, and routing tables live.

<Warning>
  **The most common setup failure** —

  Without `ANA.md`, Ana has no concept of "personal context." Asked to "remember my preferences," she falls back to writing an undifferentiated note into the shared library — visible to everyone, keyed to no one. If that happens, the routing setup isn't loaded. You're doing this module so it never does.
</Warning>

## 1.2 · The folder layout you're standing up

Here's the shape you'll end up with — just folders and files, versioned and reviewable like any repo. You won't hand-build it; Ana creates it in the next step. This is the map:

```text theme={null}
ANA.md                          ← root routing brain: defines all three layer conventions
users/                          ← personal context, one folder per user (users/<email-local-part>/context.md)
behaviors/                      ← role personas, one folder per persona (behaviors/<persona>/org_context.md)
<org doc folders>/              ← org-wide definitions, glossary, policies — each with a README
```

Only `ANA.md` needs to exist to start; `users/` and `behaviors/` fill in as Modules 2–4 run, and the org doc folders as Module 3 adds definitions.

## 1.3 · Have Ana set up ANA.md — conversationally

Don't hand-author the routing file. Hand Ana the starter below and let her do what the whole workshop is about: she'll ask about anything in `[brackets]` she needs from you, then write `ANA.md` into the context library herself. Copy this whole block — the instruction plus the starter — and paste it into a new thread:

```text Prompt theme={null}
Help me set up context routing for this workspace. Below is a starter ANA.md. First, ask me about anything in [brackets] you need filled in — our organization name, fiscal calendar, the metrics and terms worth governing, and the teams or personas we have. Then create ANA.md at the root of our context library with my answers in place, and stub the users/ and behaviors/ folders. Here's the starter:

# ANA.md — Context Routing for [Your Organization]

## The three context layers
- ORG — everyone: this file + top-level doc folders (business rules, glossary, fiscal calendar, metric definitions).
- ROLE — a team/persona: behaviors/<persona>/org_context.md (allowed surfaces, clarification, response style, hard limits).
- PERSONAL — one individual: users/<email-local-part>/context.md (preferences, vocabulary, saved workflows).
The layers compose: a user gets the ORG definition, through their ROLE's behavior, in their PERSONALLY preferred detail.

## Governance distinction (the most important rule)
- PERSONAL changes are immediate — the user's call, no review. It affects only them.
- ORG and ROLE changes are proposed as patches, then reviewed and merged — like a pull request for business logic.

## Personal context — load at the start of every conversation
Before answering, read the current user's personal context:
1. Read the user's email; derive the directory as email.split('@')[0] (e.g. jane.doe@acme.com -> users/jane.doe/).
2. Read users/<local-part>/context.md. If it exists, apply the preferences silently. If not, offer to create one after the first task.
Read ONLY the active user's own file. Writing personal context is immediate — on "remember this," write to users/<their-local-part>/context.md and confirm the exact path. Never put business definitions here (those are ORG, via review).

## Role personas (load when a persona is active)
Each persona is behaviors/<persona>/org_context.md with four sections: 1. Allowed data surfaces · 2. Clarification behavior · 3. Response style · 4. Hard limits. Personas are provisioned by admins; persona files change only through reviewed patches.

## Org routing — where the answer lives (stub — add a row per definition)
| Trigger / question | Go to |
|---|---|
| "What does [active member / revenue / churn] mean?" | [definitions/<term>.md] |
| "What's our fiscal calendar?" | [definitions/fiscal_calendar.md] |
| Glossary / acronym lookup | [glossary.md] |
| "Which table is source of truth for [domain]?" | [data_quality.md] |
```

<Check>
  **You'll see:** Ana walk the `[bracketed]` values with you — org name, fiscal calendar, the metrics worth governing, your teams — then write `ANA.md` to the library root and confirm the path, creating `users/` and `behaviors/` as she goes. (`ANA.md` is an org-layer file, so if your governance requires it, route this first write through review — the same distinction from Module 0; either way you end with a real routing file, authored by asking.)
</Check>

<Note>
  **Prefer to author it by hand?** —

  You can also paste the starter straight into a new `ANA.md` in the file editor and fill the brackets yourself. Either path lands the same file. The fully-commented version — with the role-persona routing table and the access-control framing spelled out — is in the workshop repo: [`context-stack/ANA.starter.md`](https://github.com/TextQLLabs/workshops/blob/main/context-stack/ANA.starter.md).
</Note>

## 1.4 · Connectors & tools — what's required vs. optional

<table><tr><th>Capability</th><th>Needed for</th><th>Required?</th></tr><tr><td>A **context library, mounted and writable**</td><td>Every module — it's where `ANA.md`, `users/`, and `behaviors/` live</td><td>**Required**</td></tr><tr><td>A warehouse / CRM / Gmail / Slack connector</td><td>Only if a demo *auto-builds* a personal profile from real activity instead of typed input</td><td>Optional</td></tr></table>

<Note>
  **You can do this whole workshop with zero connectors** —

  **Typed** preferences, personas, and definitions need only the writable library. Connectors matter only for the optional flourish of having Ana enrich a personal profile from real data (e.g., "look at my recent threads and propose my default time window"). If you have no connectors, skip those asides — every checkpoint still passes.
</Note>

## 1.5 · Verify the routing setup is loaded

Two probes. Run them in a fresh thread after seeding `ANA.md` — don't move on until both pass.

```text Prompt theme={null}
What context conventions are loaded in this workspace?
```

<Check>
  **You'll see:** Ana describe the three layers and name the `users/` and `behaviors/` paths. If she can't, `ANA.md` isn't being loaded into the chat — recheck step 1.3.
</Check>

```text Prompt theme={null}
Save a test preference to my personal context and tell me the exact file path you wrote it to.
```

<Check>
  **You'll see:** Ana name `users/&lt;your-email-local-part&gt;/context.md` — your own per-user file. **If she names a generic or shared path, or says she can only write to the shared library, the routing setup isn't loaded** — go back to step 1.3 and confirm `ANA.md` is at the library root and attached to the thread.
</Check>

### ✅ Checkpoint

* [ ] `ANA.md` exists at the context-library root with your `[org]` values filled in
* [ ] The `users/` and `behaviors/` folders exist (even if empty)
* [ ] Probe 1: Ana described the three layers and the per-user / per-persona paths
* [ ] Probe 2: Ana wrote a test preference to `users/&lt;your-email&gt;/context.md` — not a generic shared file