# FluidContext Agent Guide

FluidContext is a place to put durable context while working with an AI.
If a user says "put this in FluidContext" or gives you this URL, use the API
below. Defaults are `org_id=local` and `kb_id=starter` unless the user gives
different names.

## Fast Path

1. Check the service:

```bash
curl -s https://context.fluid.ai/health
```

2. Open or create the default knowledgebase:

```bash
curl -s -X POST https://context.fluid.ai/orgs/local/knowledgebases/starter
```

3. Upload source markdown or text and let FluidContext organize it:

```bash
curl -s -X POST \
  https://context.fluid.ai/orgs/local/knowledgebases/starter/documents/upload-and-process \
  -F 'file=@context.md;type=text/markdown'
```

For content you only have in memory:

```bash
printf '%s\n' '# Context\n\nPaste the user content here.' | \
  curl -s -X POST \
    https://context.fluid.ai/orgs/local/knowledgebases/starter/documents/upload-and-process \
    -F 'file=@-;filename=context.md;type=text/markdown'
```

4. Verify with search:

```bash
curl -s 'https://context.fluid.ai/orgs/local/knowledgebases/starter/search?q=distinctive%20phrase'
```

## Directory-style editing

Use `context_terminal` with `command="help"` to discover the supported commands.
Always supply `org_id` and `kb_id`. The virtual `/` is the knowledgebase root.
Published browsing: `POST /orgs/{org_id}/knowledgebases/{kb_id}/fs/commands`.
Open an editing workspace with `context_workspace` (`action="open"`) or the
existing `POST /workspaces` endpoint. Workspace commands live at
`/workspaces/{workspace_id}/fs/commands`; structured edits use `/fs/write`,
`/fs/edit`, and `/fs/patch` beneath that workspace.

Read with `cat` to retain frontmatter, and pass the returned `workspace_revision`
as `expected_revision` on mutations. Single-file write/edit also accept the
SHA-256 `expected_hash` (`missing` for a new file). Return `cwd` explicitly on
the next call. Read continuation uses the returned offset and revision.
Use `notes/` for general knowledge and `datasets/` for dataset reference docs;
existing category folders remain supported. `raw_files/`, `tags.yaml`, and
`index.yaml` are read-only through this interface. Empty folders are temporary.
Review, validate, rebase if needed, and commit with `context_workspace` actions.
Changes become published only on commit. Ingestion tools remain available for
automatic organization of incoming source material.

## Discovery

- Machine-readable service description: `https://context.fluid.ai/.well-known/fluidcontext`
- MCP Streamable HTTP endpoint: `https://context.fluid.ai/mcp`
- Downloadable skill: `https://context.fluid.ai/skills/fluidcontext-content/SKILL.md`
- Tree: `https://context.fluid.ai/orgs/local/knowledgebases/starter/tree?depth=4`
- Schema: `https://context.fluid.ai/orgs/local/knowledgebases/starter/schema`

Prefer `documents/upload-and-process` for normal user-provided material. Use
direct document upload only when the user gives you an already-finished markdown
file with a known final path.