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

# Organize your context repository

> Folder structures, file templates, and naming rules that keep context findable

## Overview

Three consumers read your folder structure:

* **People** browsing the **Context** tab.
* **Retrieval agents** traversing paths with `qontext_ls`, `qontext_find`, `qontext_grep`, and hybrid search.
* **Continuous update agents** placing each incoming record.

All three need the same thing: shallow folders with non-overlapping purposes, and one home per entity.

Qontext proposes a structure when your repository is first built. You can change it at any time.

***

## Recommended structure

Organize the top level by **ownership and lifecycle**, not by topic:

<Tree>
  <Tree.Folder name="agents" defaultOpen>
    <Tree.Folder name="skills" />
  </Tree.Folder>

  <Tree.Folder name="company" />

  <Tree.Folder name="teams" defaultOpen>
    <Tree.Folder name="engineering" />

    <Tree.Folder name="sales" />
  </Tree.Folder>

  <Tree.Folder name="projects" />
</Tree>

| Folder      | Holds                                                            | Lifecycle                          |
| ----------- | ---------------------------------------------------------------- | ---------------------------------- |
| `agents/`   | Reusable agent instructions and resources, including `skills/`   | As long as agents use it           |
| `company/`  | Organization-wide knowledge: strategy, policies, positioning     | Superseded, never closed           |
| `teams/`    | Responsibilities, processes, and relationships owned by one team | Ends when the responsibility moves |
| `projects/` | Initiatives with a defined outcome and end                       | Ends when the initiative does      |

This resolves the ambiguous case: a customer account belongs to the team that owns it, while a time-boxed migration for that same customer belongs in `projects/` and links back to the account.

Matches the [repository root structure file](/features/structure-files#organize-the-repository-root) template.

<Info>
  **By business function instead.**

  `engineering`, `growth`, `operations`, `product` works when every topic has one departmental home. It breaks as soon as work crosses functions, because a cross-team initiative then has several plausible homes.
</Info>

***

## Principles

* **One entity, one primary record.** One file per customer, person, project, or topic. Search before creating; update rather than add a second record.
* **Link instead of copying.** References are returned inline as file IDs, so an agent follows a link straight into `qontext_cat`. A copy diverges silently; a link cannot.
* **Keep folder purposes non-overlapping.** [Continuous updates](/features/continuous-updates) read the structure files of every folder that could hold a record. Where two folders both qualify, strictness decides placement — not your intent.
* **Name for retrieval.** Agents traverse paths before reading content. `teams/sales/customers/acme/overview.md` says what it contains; `teams/sales/docs/file-2.md` does not.
* **Create folders when content arrives.** Every empty folder is a path an agent must consider and rule out.

<Info>
  **Access boundaries follow your folder tree.**

  Access widens deeper in the tree but never narrows — restricting a subtree means setting the narrower access on its parent. Content that only some members or [API keys](/features/access-management#access-controls-for-api-keys) should reach needs its own subtree from the start, not a restricted file inside an open folder. See [Access management](/features/access-management).
</Info>

***

## Naming conventions

| Convention                                   | Example                                  |
| -------------------------------------------- | ---------------------------------------- |
| Lowercase with hyphens                       | `northstar-industries.md`                |
| ISO date prefix on dated records             | `2026-09-04-quarterly-review.md`         |
| `overview.md` for an entity's primary record | `teams/sales/customers/acme/overview.md` |
| Name the entity, not its category            | `jane-smith.md`, not `contact-1.md`      |
| Preserve required names exactly              | `SKILL.md`, `.qontext.structure.md`      |

Date prefixes sort chronologically and make a record's period visible in a `qontext_ls` listing without reading it.

***

## Folder patterns

### Sales and customer knowledge

<Tree>
  <Tree.Folder name="teams" defaultOpen>
    <Tree.Folder name="sales" defaultOpen>
      <Tree.Folder name="customers" defaultOpen>
        <Tree.Folder name="acme" defaultOpen>
          <Tree.File name="overview.md" />

          <Tree.Folder name="meetings" defaultOpen>
            <Tree.File name="2026-09-04-quarterly-review.md" />
          </Tree.Folder>

          <Tree.Folder name="support" defaultOpen>
            <Tree.File name="sso-login-failure.md" />
          </Tree.Folder>

          <Tree.Folder name="contacts" defaultOpen>
            <Tree.File name="jane-smith.md" />
          </Tree.Folder>
        </Tree.Folder>
      </Tree.Folder>

      <Tree.Folder name="pipeline" defaultOpen>
        <Tree.Folder name="northstar" defaultOpen>
          <Tree.File name="overview.md" />
        </Tree.Folder>
      </Tree.Folder>

      <Tree.Folder name="rev-ops" defaultOpen>
        <Tree.File name="deal-stages.md" />

        <Tree.File name="qualification-criteria.md" />

        <Tree.File name="sales-handoff.md" />
      </Tree.Folder>
    </Tree.Folder>
  </Tree.Folder>
</Tree>

| Location      | Contains                                                              |
| ------------- | --------------------------------------------------------------------- |
| `customers/`  | One folder per customer company                                       |
| `pipeline/`   | One folder per prospective company                                    |
| `overview.md` | Status, owner, sources, snapshot, contacts, motivation, dated history |
| `meetings/`   | One dated record per meeting                                          |
| `support/`    | One record per distinct issue                                         |
| `contacts/`   | One record per person                                                 |
| `rev-ops/`    | Sales definitions and procedures shared across accounts               |

Northstar has only `overview.md` because nothing else exists yet — the subfolders appear when content does.

One location per company. Let your CRM decide `pipeline` or `customers`; when the status changes, move the folder in the **Context** tab rather than creating a second record. Use the [sales structure file](/features/structure-files#aggregate-customer-knowledge) template to automate this layout.

### Projects

<Tree>
  <Tree.Folder name="projects" defaultOpen>
    <Tree.Folder name="customer-portal" defaultOpen>
      <Tree.File name="overview.md" />

      <Tree.Folder name="decisions" defaultOpen>
        <Tree.File name="2026-09-02-authentication.md" />
      </Tree.Folder>

      <Tree.Folder name="meetings" defaultOpen>
        <Tree.File name="2026-09-04-kickoff.md" />
      </Tree.Folder>
    </Tree.Folder>
  </Tree.Folder>
</Tree>

One primary home per cross-team project, linked from each team involved. Goal, owner, status, milestones, risks, and next steps go in `overview.md`; decisions and meetings get their own files. Use the [project summaries structure file](/features/structure-files#keep-project-summaries-current) template.

### Agent skills

<Tree>
  <Tree.Folder name="agents" defaultOpen>
    <Tree.Folder name="skills" defaultOpen>
      <Tree.Folder name="prepare-customer-meeting" defaultOpen>
        <Tree.File name="SKILL.md" />

        <Tree.Folder name="references" defaultOpen>
          <Tree.File name="briefing-format.md" />
        </Tree.Folder>
      </Tree.Folder>
    </Tree.Folder>
  </Tree.Folder>
</Tree>

One folder per skill, named to match the `name` in `SKILL.md`. Supporting files go in `references/`, `scripts/`, or `assets/` and load only when needed. Link to shared company knowledge rather than copying it into each skill. See [Skills distribution](/features/skills#organize-a-skill).

***

## File templates

Fictional examples. Adapt the sections, not the content.

### Entity overview

**Place at:** `<entity folder>/overview.md`

**Use when:** A customer, prospect, person, product, or team needs one record answering the common questions.

```md overview.md theme={null}
# Acme

| Metadata | Value |
| --- | --- |
| Status | POC |
| Owner | Maya Chen |
| Sources | HubSpot: Acme; Slack: #acme-x-qontext; Notion: [Weekly] Team check-out |

## Snapshot

One open POC in the Customers pipeline: a six-week test with Acme's support organization. The workspace holds roughly 400 files after one restructure. As of 2026-09-04, two groups and nine users are active.

## Contact person

Jane Smith — Head of Support: project sponsor and Qontext admin. Requested the separate testing workspace. Email: jane.smith@acme.example.

Tom Alvarez — role not recorded: joined the initial scoping meeting. Email: tom@acme.example.

## Why they want to work with us

Phase one gives support agents policy and account context from Salesforce and public Slack channels. Phase two tests whether the same layer serves the sales organization; the Head of Support has brought two engineers in to evaluate it.

## History

2026-09-05: Three users could not complete SSO login. Cause not confirmed; tracked as [SSO login failure](support/sso-login-failure.md).

2026-09-04: The [quarterly review](meetings/2026-09-04-quarterly-review.md) confirmed Salesforce and Slack as the initial sources.

2026-08-21: Acme restructured the repository and began testing. Retrieval was about 1.1 seconds across several hundred files.

## Other

Customers pipeline; POC; open; high priority.

Open support: SSO login failure affecting accounts created before 2026-08-20.

Recommended setup: repository default member access set to no access, department folders shared to groups.
```

An overview carries **durable state** — what is true now, and the dated history behind it. Action items and open questions belong in the [meeting record](#meeting-record) that raised them; here they go stale within days and lose their origin.

Mark what a source does not establish, in place: "role not recorded", "cause not confirmed". Otherwise an agent answering from this file presents your inference as fact.

### Meeting record

**Place at:** `<entity folder>/meetings/YYYY-MM-DD-<topic>.md`

**Use when:** A conversation produced decisions or actions that later work depends on.

```md 2026-09-04-quarterly-review.md theme={null}
# Quarterly review — Acme

**Date:** 2026-09-04
**Attendees:** Maya Chen, Jane Smith, Tom Alvarez
**Source:** HubSpot meeting note

## Decisions

- Salesforce and Slack are the initial sources for the pilot.

## Discussion

- Support volume has doubled since June; Acme wants agents to answer from account history.
- The sales expansion depends on a successful support pilot.

## Actions

- Maya: confirm the Salesforce scope by 2026-09-11.
- Jane: validate the SSO fix with three test users.

## Open questions

- Whether the sales expansion needs a separate agreement.
```

One meeting per file, and the home for action items and open questions — both stay tied to the conversation that produced them. Where the meeting exists in a source, link it and update this file when the source note changes.

### Decision record

**Place at:** `projects/<project>/decisions/YYYY-MM-DD-<topic>.md`

**Use when:** A choice constrains later work and its reasoning must outlive the people who made it.

```md 2026-09-02-authentication.md theme={null}
# Authentication for the customer portal

**Date:** 2026-09-02
**Status:** Accepted
**Owner:** Tom Alvarez

## Decision

Use the existing SSO provider for the customer portal instead of building a separate login.

## Context

Two options: extend the current SSO provider, or run a standalone identity service for external users.

## Reasoning

Extending SSO reuses the audited login path and avoids a second set of credentials. The standalone service would have supported per-customer branding, which no customer has asked for.

## Consequences

- External users need accounts in the SSO provider.
- Per-customer branding requires revisiting this decision.

## Supersedes

Nothing.
```

Mark a superseded decision and leave it in place rather than deleting it.

### Issue record

**Place at:** `<entity folder>/support/<issue>.md`

**Use when:** A distinct problem needs its own investigation thread, separate from the entity overview.

```md sso-login-failure.md theme={null}
# SSO login failure

**Status:** Open
**Reported:** 2026-09-05 by [Jane Smith](../contacts/jane-smith.md)
**Affects:** [Acme](../overview.md)

## Symptom

Three Acme users cannot complete SSO login. The provider returns a valid assertion and no session is created.

## Confirmed

- Reproduced for two of the three reported accounts.
- Only accounts created before 2026-08-20 are affected.

## Not confirmed

- Whether the provider's recent metadata change is the cause.

## Next steps

- Compare the assertion for an affected and an unaffected account.
```

The **Confirmed** and **Not confirmed** split is the point: an agent answering from this file must not pass an open hypothesis off as established.

***

## Anti-patterns

| Pattern                                             | Failure                                    | Fix                                            |
| --------------------------------------------------- | ------------------------------------------ | ---------------------------------------------- |
| One company under both `customers/` and `pipeline/` | Two partial answers, neither current       | One folder per company, moved on status change |
| A `misc/`, `general/`, or `docs/` folder            | Nothing is decidably out of scope          | Name folders by what belongs in them           |
| `teams/sales/emea/enterprise/accounts/acme/`        | Every level is another path to traverse    | Keep only levels that carry meaning            |
| A policy copied into several folders                | Copies diverge; none is authoritative      | One record, linked                             |
| Restricted content in an open folder                | Access cannot narrow further down the tree | Give it its own subtree                        |
| Placeholder files and empty folders                 | Paths that return nothing                  | Create them when content exists                |
| Dates inside the file but not in its name           | Same-topic records collide in a listing    | Prefix with the ISO date                       |

***

## Check your structure

Each case should have exactly one answer:

| Case                                                   | One correct home                      |
| ------------------------------------------------------ | ------------------------------------- |
| A meeting note for an existing customer                | That company's `meetings` folder      |
| A prospect becomes a customer                          | The existing company folder, moved    |
| A policy published in Confluence                       | The policies folder under `company`   |
| A migration for one customer, staffed across two teams | `projects/`, linked from both teams   |
| A reusable instruction set for an agent                | Its own folder under `agents/skills/` |
| A person working at two accounts you track             | One contact record, linked from both  |

Two plausible homes means that boundary is not distinguishable yet. Tighten the folder definitions, then record the rule in the folder's [structure file](/features/structure-files).

***

## Set up your structure

<Steps>
  <Step title="Shape the top level">
    In the **Context** tab, create your top-level folders. Every one is a boundary you will maintain, so keep the count small.
  </Step>

  <Step title="Write the root structure file">
    Add `/.qontext.structure.md` from the [repository root template](/features/structure-files#organize-the-repository-root). Root guidance is inherited by every folder, so shared conventions belong here and nowhere else.
  </Step>

  <Step title="Set access on folders, not files">
    Set restrictions on the parent of the subtree you want to limit. See [Access management](/features/access-management).
  </Step>

  <Step title="Add folder-specific guidance">
    Give folders with their own rules — accounts, policies, projects — a [structure file](/features/structure-files) covering only what differs from the root.
  </Step>

  <Step title="Review what lands">
    Watch the **Changes** tab. Misplacements and duplicates point at a folder boundary that needs sharpening, not a missing folder.
  </Step>
</Steps>

***

## Prompts to get started

* "List my top-level folders and tell me which two have the most overlapping purpose."
* "Find companies that appear in both `customers` and `pipeline`, and propose which record should survive."
* "Which folders contain no files, or only a single placeholder file?"
* "Draft an `overview.md` for `teams/sales/customers/acme` from everything you can find about Acme."