Skip to content

Docs: user-manual pass + Contexts screenshot, drop external links #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tanglearncode merged 2 commits into from
Jul 20, 2026
Merged

Docs: user-manual pass + Contexts screenshot, drop external links #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c7306c0
Add Contexts page screenshot; drop external MCP links
tanglearncode Jul 20, 2026
fd3d092
Rework docs into a followable user manual; drop internal details
tanglearncode Jul 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 51 additions & 129 deletions docs/core-concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,66 +4,53 @@ sidebar_position: 3

# Core Concepts

NeatContext organizes the context an AI client uses, scopes it **per Context
workspace**, and hands it off over a local MCP connection — **without running a
model of its own**. This page explains each piece and how they combine. (Each has
a full [feature page](/category/features) as well.)

## NeatContext runs no model

This is the idea everything else follows from. NeatContext does **not** host a
chat, does **not** call a model, and does **not** store a model API key. It is a
**control center**: you curate context in it, and your existing AI client — Claude
Code, Claude Desktop, Codex CLI, or ChatGPT Desktop — does the reading,
searching, tool-calling, and answer-writing with its own model.

When you connect a client, NeatContext exposes a small, read-only local MCP
server. The client calls **`get_context`** and receives **pointers, not content**:

- the **domain profile file paths** to read,
- the **knowledge folder paths** to search, and
- the **extension tools** available on this connection.

The client then reads those files, searches those folders, and calls those tools
itself. NeatContext never uploads your corpus and never sees the client's model.

## The Library holds reusable resources

The **[Library](./features/library.md)** is your local registry of reusable
resources:

- **Domain profiles** — Markdown files you create in-app or **link in place**
from disk.
- **Knowledge folders** — local folders you link in place.
- **Extensions** — read-only tool connectors (bundled, personally added, or from
a shared team Library).

A Library resource can be selected by many Contexts. Removing it from a Context
never deletes it from the Library or from disk. An optional **read-only Team
Library** — any folder following the `profiles/` + `knowledge/` + `extensions/`
convention (typically a git clone) — lets a team share approved resources.

## The Context is the unit of handoff

A **[Context](./features/contexts.md)** is a named workspace for one operational
scope, shown as a **tab**. Each Context selects its own:

1. **domain profiles** (one of them **active**),
2. **knowledge folders**, and
3. enabled **extensions**.

Because context is per-Context, you never swap things in and out: keep *Team A's*
profile and runbooks in one Context tab and *Team B's* in another, and connect a
client to whichever you need. Every AI-client session is pinned to exactly one
Context.

## Domain profiles

A **domain profile** is a Markdown file describing a team or domain: what it
owns, how it investigates, and the actions it must not take. The connected client
reads the active profile completely and treats it as its primary behavioral guide.

Profiles use YAML front matter for metadata, followed by free-form Markdown:
NeatContext is a control center for the context your AI uses. You curate that
context here, then connect the AI client you already work in and ask your
questions there. This page introduces the vocabulary you'll see in the app.

## What you work with

- **Domain profile** — a Markdown file describing a team or domain: what it owns,
how it investigates, and what it must never do.
- **Knowledge base** — a local folder of documents (runbooks, TSGs, postmortems)
your AI can search and cite.
- **Extension** — a read-only connector that gives your AI tools for a real system
(incidents, logs, deployments).
- **Library** — where your profiles, knowledge folders, and extensions live so you
can reuse them.
- **Context** — a named workspace, shown as a tab, that selects the profiles,
knowledge folders, and extensions for one job.
- **AI client** — the app you already use to talk to a model (Claude Code, Claude
Desktop, Codex CLI, or ChatGPT Desktop). NeatContext brings no model of its own.

## How the pieces fit

1. **Add resources to your [Library](./features/library.md).** Create or link
[domain profiles](./features/domain-profiles.md), link
[knowledge folders](./features/knowledge-bases.md), and install any
[extensions](./features/using-extensions.md) you need.
2. **Build a [Context](./features/contexts.md).** On a Context tab, select the
profiles, knowledge folders, and extensions for the job, and mark one profile
**active**.
3. **[Connect your AI client](./features/connect-ai-clients.md).** Click **Connect**
and ask your question in the session that opens. The answer ends with a
**Sources** list of the files and tools it used, so you can verify it.

## The Context is the unit

A **Context** carries its own profiles, knowledge folders, and extensions, so you
never swap things in and out. Keep *Team A's* profile and runbooks in one Context
tab and *Team B's* in another, and connect a client to whichever you need.

That is what makes NeatContext's core advantage possible: give two teams their own
Context for the **same** incident, and each correctly reaches its **own** right
action — one hands off, the other fixes the root cause. The
[Incident Analysis walkthrough](./guides/incident-analysis.md) shows this end to
end.

## Anatomy of a domain profile

A profile is plain Markdown with optional YAML front matter for metadata:

```markdown
---
Expand All @@ -87,72 +74,7 @@ Infra Team owns the shared infrastructure that product teams build on…
- Do not fail over the billing-postgres primary during business hours.
```

Good profiles are explicit about three things: **what the team owns**, its
**first checks / investigation order**, and its **guardrails** (dangerous
actions). Those sections are what turn a generic model into a team-specific one.

Profiles are plain Markdown you own and version however you like.
→ Full details: [Domain Profiles](./features/domain-profiles.md)

## Knowledge bases

A **knowledge base** is a local folder of documents — typically a team's
**runbooks**, **troubleshooting guides (TSGs)**, and **postmortems**. The
connected AI client searches the attached folders — in place, locally on your
machine — to ground its answer, and cites the documents it used as **clickable
`file://` sources** at the end of the answer.

Because a knowledge base is just a folder on disk, you keep it in whatever repo
you already use.
→ Full details: [Knowledge Bases](./features/knowledge-bases.md)

## Extensions

An **extension** is a read-only connector that gives your AI **tools** for your
real systems — read an incident, search logs, list deployments. Each one is a
local stdio MCP server; when a client is connected, NeatContext advertises the
selected extension's tools on the same connection and **proxies** each call,
injecting the extension's credentials from your OS keychain so the client never
sees a secret.

Extensions declare how they authenticate, which determines the Connect
experience: nothing to configure, an inline **API-key form** (the bundled
Datadog), or **OAuth in your browser** (the bundled PagerDuty). Credentials are
encrypted with your OS secure storage and stay on your machine.
→ Using them: [Using Extensions](./features/using-extensions.md) ·
Building them: [Building Extensions](./extensions/overview.md)

## AI clients

You connect one of the supported clients — **Claude Code**, **Claude Desktop**,
**Codex CLI**, or **ChatGPT Desktop** — from the Context page. NeatContext opens
a **fresh, Context-pinned session** with an invocation-scoped or project-scoped
MCP configuration; it never rewrites your global client config. The client brings
its own model.
→ Full details: [Connecting AI Clients](./features/connect-ai-clients.md)

## How it all fits together

```text
┌───────────────────── One Context workspace ──────────────────────┐
│ │
│ Active profile + Knowledge folders + Extensions │
│ (how to reason) (what to cite) (tools to call) │
└──────────────────────────────┬───────────────────────────────────┘
│ Connect (local MCP)
▼
Your AI client — Claude Code / Claude Desktop /
Codex CLI / ChatGPT Desktop
│
get_context → reads files, searches folders, calls tools
▼
Grounded, team-specific answer with a ## Sources footer
```

Edits you make to a connected Context are picked up on the client's **next**
`get_context` call — no reconnect needed. Selecting a different Context tab does
**not** retarget an open session; connect again to open a new session for it.

The [Incident Analysis walkthrough](./guides/incident-analysis.md) shows this in
action: the same incident and the same tools in two Contexts, with two different
profiles and knowledge bases, produce two different — and both correct — outcomes.
The sections that matter most are **what the team owns**, its **first checks**, and
its **guardrails** (dangerous actions). Those turn a generic answer into a
team-specific one. Full guidance is in
[Domain Profiles](./features/domain-profiles.md).
130 changes: 36 additions & 94 deletions docs/features/connect-ai-clients.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,110 +4,52 @@ sidebar_position: 5

# Connecting AI Clients

NeatContext does **not** host or resell a model, and it never asks for a model API
key. Your answers come from the AI client you already use. NeatContext's job is to
hand that client the right context — over a local [MCP](https://modelcontextprotocol.io)
connection — and then get out of the way while the client reads, searches, calls
tools, and writes the answer with **its own** model.
Your answers come from the AI client you already use — NeatContext just hands it
the context you selected. There is no model, base URL, or API key to set up in
NeatContext.

## Supported clients

| Client | How it connects |
|---|---|
| **Claude Code** (CLI) | A fresh `claude` session, MCP passed for that invocation only. |
| **Claude Desktop** | A new session in Claude Desktop's built-in **Claude Code**. |
| **Codex CLI** | A fresh Codex TUI session, MCP passed for that invocation only. |
| **ChatGPT Desktop** | A new chat in ChatGPT Desktop's built-in **Codex**. |
- **Claude Code** (CLI)
- **Claude Desktop** (uses its built-in Claude Code)
- **Codex CLI**
- **ChatGPT Desktop** (uses its built-in Codex)

Each card on a Context's **Connect this context** panel shows a readiness hint —
*Ready to connect*, *…not found* (client not installed), or *Build required* (the
native backend still needs building, only in a source build).
Each client has a card in a Context's **Connect this context** panel, with a
readiness hint: *Ready to connect*, *…not found* (the client isn't installed), or
*Build required* (only in a source build).

## How to connect
![The Connect this context panel on the Context page, with a Connect button on each of the ChatGPT Desktop, Claude Desktop, Codex CLI, and Claude Code CLI cards](/img/features/contexts-page.png)

1. Open **Contexts** and select the Context tab you want to hand off.
2. Attach its domain profiles (mark one active), knowledge folders, and any
trusted read-only extensions.
3. In **Connect this context**, click **Connect** on the client you use.
4. If the client prompts you, **trust** the NeatContext-managed workspace and
**approve** the `neatcontext` MCP tools.
5. Ask your question in the session that opens.

Every **Connect** opens a **fresh** session — NeatContext does not resume or scan
your past conversations. It never rewrites your global client configuration:
CLI clients get MCP only for that one invocation, and desktop clients get a
project-scoped config inside a NeatContext-managed workspace.

## What the client receives

Once connected, the client can call one read-only tool plus one tool per selected
extension tool:

- **`get_context`** returns the connected Context as **pointers, not content**:
the domain profile file paths to read, the knowledge folder paths to search, and
the extension tools available on this connection — with the instruction to use
them itself.
- **One tool per selected extension tool** (for example `demo_search_logs`),
proxied to that extension's local MCP server with your connection injected from
the OS keychain. The client calls live systems directly but **never sees a
secret**.

During the MCP `initialize` handshake, NeatContext also supplies its analysis and
output instructions, so the client grounds claims in what it actually read, labels
hypotheses, and ends the answer with a **`## Sources`** section citing the exact
files (as `file://` links with line ranges) and tools it used.

## Context pinning and live edits

- **Pinned to one Context.** Sessions launched for the same Context share its
runtime; different Contexts use different runtime and workspace paths, so a later
connection never retargets an earlier session.
- **Live edits.** The MCP server (and, for the desktop clients, a prompt hook)
reread the Context's runtime file, so adding or removing profiles, folders, or
extensions in NeatContext is visible on the client's **next** `get_context`
without reconnecting.
- **Deleted or disconnected Context.** If a Context's runtime is removed, the
client gets an actionable *connect from NeatContext first* message instead of
answering from stale context.
## Connect a client

## The runtime boundary

The Context runtime file NeatContext writes for a connection contains **only
nonsecret metadata**: profile paths, knowledge-folder paths, allowed extension
commands and tool schemas, and keychain *references*. Extension secrets stay in
your OS keychain and are injected only into the extension process, per call — never
written into a runtime file or exposed to the client.

## Per-client notes

### Claude Code

A fresh `claude` interactive session in a stable per-Context managed workspace
containing only a `UserPromptSubmit` hook; the MCP server is passed via
`--mcp-config` for that invocation. Use `/mcp` inside Claude Code to inspect the
connection and its tools.

### Claude Desktop

Opens a new session in Claude Desktop's built-in **Claude Code** surface (not a
plain Claude chat) through a `claude://code/new?folder=…` link. Confirm the folder
and approve the tools when prompted.
1. Open **Contexts** and select the Context tab you want to use.
2. Add its domain profiles (mark one **active**), knowledge folders, and any
extensions.
3. In **Connect this context**, click **Connect** on your client's card.
4. If the client asks, **trust** the folder it opens and **approve** the
`neatcontext` tools.
5. Ask your question in the session that opens.

### Codex CLI
Every **Connect** opens a **new** session — it does not reopen a past
conversation. To use a different Context, select its tab and click **Connect**
again.

A fresh Codex TUI session started with `-C` in a stable per-Context workspace; the
MCP server is supplied through invocation-scoped `-c` overrides. NeatContext never
edits your `~/.codex/config.toml`. Codex applies its normal project-hook trust
review.
## Ask your question

### ChatGPT Desktop
Ask your question normally in the session NeatContext opened. Your AI client reads
the Context's profile, searches its knowledge folders, and calls its extension
tools on its own, then writes an answer that ends with a **`## Sources`** list of
the exact files and tools it used. Open a source to check the answer against your
own document.

Opens a new chat in ChatGPT Desktop's built-in **Codex** host (not a hosted plain
ChatGPT chat) through a `codex://threads/new?path=…` link. Review and trust the
managed workspace, hook, and MCP tools when prompted.
:::tip[Edit a Context without reconnecting]
If you change a connected Context (add a profile, folder, or extension), just ask
your next question — the client picks up the change automatically. You only need to
**Connect** again to start a session for a *different* Context.
:::

:::note[No model configuration, ever]
There is no model provider, base URL, or API key anywhere in NeatContext. If you
expected a "connect your model" step from an older version, it has been removed —
the connected AI client brings the model.
:::note[No model setup]
If you're looking for a "connect your model" step, there isn't one — the connected
AI client brings the model.
:::
8 changes: 3 additions & 5 deletions docs/features/context-activity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,9 @@ changes the app's active Context).
## What's recorded

- **Sessions opened** — when a client connected to this Context.
- **Context injections** — when the current Context was served to the client
(via `get_context` or the per-prompt hook).
- **Tool calls** — each extension tool the client invoked, with timing and a
**truncated preview**. Full tool payloads are **not** stored by default, and
credentials and sensitive fields are redacted.
- **Context handoffs** — when this Context was handed to the client.
- **Tool calls** — each extension tool the client used, with timing and a short
preview. Full tool payloads aren't stored, and credentials are hidden.

This is how you verify a Context: connect a client, ask a question, then read the
log to confirm which profiles, folders, and tools were actually served and run.
Expand Down
Loading
Loading