LLeMbas-CLI/harness/filesystem.md

# The file system a session works in

Spec 3.0.0. **Two worlds, one harness.** A **chat** (a conversation on the server) works in the
server's file system: a tree kept by the instance, which may hold repositories mounted from a forge.
An **agent** session (LLeMbas CLI, Desktop's agent, or an agent chat the web UI runs on a linked
device) works in its working directory on its own machine. Neither sees the other's files. What
the two share is this contract: how paths read, what kinds of node there are, how access is said,
what an error says, how a listing and a search look, and how instruction files are collected. The
tools are the same names and schemas on both sides (`tools/*.json`, `sessions`); where a tool exists
on one side only, it says so there.

The conformance areas are `fs_access` (the view and its errors) and `instructions` (the instruction
chain). An agent session's local disk is the special case of one node kind less (no mounts) and
one access level for the whole working directory, decided by the CLI's permission rules and modes
(`permission/`) rather than by the table below.

## Paths

- **Absolute** paths begin with `/`, the root of the tree: the organisation's root on the server,
  the file system's root on a device.
- **Relative** paths resolve against the session's **start directory** (its working directory).
- `.` and `..` are resolved by their text, before anything is looked up; `..` above `/` stays at
  `/`. Repeated `/` count as one, and a trailing `/` changes nothing. On the server there are no
  links: a path is what it says. On a device, a link is followed, and where the CLI's rules look at
  a path they look at where it really is (an `AGENTS.md` committed as a link to a file outside the
  project is not read).
- Every answer names a path in its **absolute, resolved** form, whatever the call gave — an
  error, a refusal, a search's results, a tool's own message. **The one exception is a result's
  bracket** (`context.md`): a read's header, an edit's bracket and the compaction table name the
  path as the call gave it, so the model recognises what it wrote. What identifies a file, there
  too, is its absolute path. A listing names entries by their names under the directory listed
  (*A listing*).
- Names are case-sensitive, `/`-separated, and never empty, `.` or `..`.

## Node kinds

| Kind | What |
|---|---|
| `dir` | a directory of the tree |
| `file` | a file: bytes, with a content hash (SHA-256) |
| `mount` | a directory that is a repository on a forge, at one branch. Below it, every node is a `dir` or a `file` of that repository. Server only |

A session has a **boundary** (what it may see at all: the root, a directory, one repository) and a
**start directory** inside it. On a device the boundary is the project root (the directory the
CLI's trust is given to) and the start directory is where the session started.

## Access levels

Each path is at one of four levels for a session:

| Level | Name | Read | Change | Commit |
|---|---|---|---|---|
| `none` | no access | no | no | no |
| `ro` | read-only | yes | no | no |
| `stage` | read/write, stage | yes | yes | no |
| `commit` | read/write, commit | yes | yes | yes |

- **Inside a mount**, `stage` means a change goes into the session's **working copy** (kept by the
  instance) and stops there; `commit` means the session may also send it to the forge (`commit`,
  `branch`, `pr`, `merge`, `tag`, `release`). Outside mounts there is nothing to commit, and the
  two write levels mean the same: write.
- **A grant** names a path and a level, and covers everything below the path. **The most specific
  grant wins**: `/` at `ro` and `/Notes` at `stage` make `/Notes/a.md` writable and `/b.md`
  read-only; `/Notes/Private` at `none` takes that directory away again.
- **A floor** is a maximum level per path, set where the session cannot widen it (the data group's).
  The most specific floor entry applies; the level a session has is its grant, lowered to the floor.
- A path with no grant on it or above it is at `none`. **Only what is at `ro` or above exists for
  the model.** On a mount, the forge decides first: a level is never above what the user's own
  forge account may do there.
- The levels a session has are told to the model (`prompts/blocks/workspace.md`, `{{view}}`): every
  granted path with its level, so it knows the full paths it may use.

### A granted path under a path that is not

The tree `/AGENTS.md`, `/Dir1/`, `/Dir1/FILE1.txt`, `/Dir1/Dir3/`, `/Dir2/`, with `/AGENTS.md` and
`/Dir1/Dir3/` granted and nothing else:

- The model sees **`/AGENTS.md` and `/Dir1/Dir3/`**, each **by its full path**, and everything below
  `/Dir1/Dir3/`.
- `/` and `/Dir1` are **passages**: at `none`, with something granted below. A passage is denied for
  reading and writing alike: `list /Dir1`, `read /Dir1/FILE1.txt`, `write /Dir1/new.txt` and
  `mkdir /Dir1/x` all answer `Access denied: … is not open to this session.`
- A listing never reveals a sibling: nothing lists `/Dir1`, and a listing of a granted directory
  shows only its entries at `ro` or above.
- **A path the session cannot see is answered by what the model already knows**: by its nearest
  ancestor that is either visible or a passage. Under a visible directory it is
  `No such file or directory`; under a passage, `Access denied`. So `/Dir2/b.md` (hidden) and
  `/Nope.md` (missing) get the same answer here — both under the passage `/` — and a hidden entry
  under a granted directory reads exactly as a missing one.
- A search (`glob`, `grep`, `search`) rooted at a granted directory finds what is granted below it,
  however it is reached; one rooted at a passage is denied like a listing.
- **An instruction file in a passage is not loaded** (below).

**One thing cannot be hidden**, and the spec accepts it: under a directory the session may write, a
name taken by an entry at `none` cannot be created. Making it answers `Access denied` for that path,
which says the name is taken and nothing else — not its kind, its size or what is in it.

## What each operation needs

| Operation | Tools | Needs |
|---|---|---|
| look | `list`, `read`, `glob`, `grep`, `search`, `show`, `python`'s `files`, `skill_view`, `skills_list` | `ro` |
| change | `write`, `edit`, `mkdir`, `mv` (the source and the target's directory), `rm`, `python`'s `save`, `skill_manage` | `stage` |
| commit | `commit`, `branch`, `pr`, `merge`, `tag`, `release` | `commit`, inside a mount |

A new path takes the level of the most specific grant above it. `mv` between a mount and the rest
of the tree, or between two mounts, is refused; `rm` of a mount itself is refused (a mount is
removed by whoever mounted it, not by a session). `rm` on the server moves to the **trash**,
restorable from the file explorer; inside a mount it stages the deletion.

## Errors

A tool's error is its result (`loop.json` `parallel`). The texts, exactly, with `{path}` the
resolved absolute path:

| Case | Text |
|---|---|
| not visible (missing, or at `none`), and its nearest visible-or-passage ancestor is visible | `No such file or directory: {path}` |
| a passage; not visible with a passage as that ancestor; a name taken by an entry at `none` | `Access denied: {path} is not open to this session.` |
| a change at `ro` | `Read-only: {path} can be read in this session but not changed.` |
| a commit at `stage` | `Not committed: this session may change {path} but not commit it; the change stays staged.` |
| a commit outside every mount | `Nothing to commit: {path} is not in a repository.` |
| a directory where a file was meant | `Is a directory: {path}` |
| a file where a directory was meant | `Not a directory: {path}` |
| `mv`'s target, or a file `mkdir` was asked to make | `Already exists: {path}` |
| a tool whose `requires` is not met at the time of the call | the tool's `unavailable` text |

A missing file is `No such file or directory` for **every** tool that needs it to exist — `read`,
`edit`, `show`, `list`, `glob`, `grep`, `python`'s `files` — with no hint after it: in a chat a
hidden file must read exactly as a missing one, and a hint ("use write to create it") would say
which. The tool's description says what it needs.

`write` and `edit` refuse to change an existing file the session has not seen, or one that changed
since it last saw it (by reading it, or by its own change). The texts, exactly:

| Case | Text |
|---|---|
| the file exists and this session has not read it | `{path} exists and has not been read in this session. Read it first.` |
| it changed since this session last read or changed it | `{path} changed since you last read it. Read it again before changing it.` |

How a change is noticed is each side's: the content hash on the server, the modification time on a
device.

A device's own errors (a file too large, a binary file, a protected path) are the CLI's and stay as
they are; the ones above it says the same way.

## A listing

`list` and a directory given to `read`: one entry per line, directories (and mounts) with a trailing
`/`, then — in a chat — a mount marked ` [mount]` and an entry the session can read but not change,
in a directory it can, marked ` [read-only]`. Directories first, then by name in code-point order
(`B` before `a`). An empty directory is `(empty directory)` from `read`, `(empty)` from `list`.

`list` with a `depth` (default 2, at most 6) is a tree: the entries of the directory listed, and
under each directory the entries of that directory, each level indented by two more spaces, down to
`depth` levels in all (depth 1 is the directory's own entries). The order and the marks are a single
listing's, at every level; a directory's entries come right after it. At most 400 lines, then
`(more entries — list a directory further down)` on its own line. A device leaves out ignored and
build directories (`.git`, `node_modules`, …, and what `.gitignore` says) and shows only
directories that hold a file it would list.

```
docs/
  guide/
  index.md
repo/ [mount]
  src/
  README.md [read-only]
notes.md
```

## A search

`search(query, path?, limit?)` ranks passages by meaning (embeddings) and by words (full-text) fused
by rank, then keeps only what the session's view allows — **after** scoring, so a hidden file
changes neither the results nor how many there are. A result is the passage's path and line range,
then the passage:

```
/Notes/setup.md:12-30
<the passage>
```

`grep` is the exact counterpart (text or a pattern), over the same view.

### Indexing, by tokens

What `search` reads is built when a file is written (a mount: its default branch, and again for the
files a new commit changes). The index is keyed by **content hash**, so a file in many places, or
unchanged across commits and branches, is embedded once; a rename or a move costs nothing.

Text is cut into pieces **by tokens, not by characters**: an embedder refuses input past its
context (512 tokens is common), and dense text — another language than English, code, hashes —
holds far more tokens per character than prose. A piece is at most **480 tokens** (`size`; room for
the embedder's own markers under 512) and repeats the last **64 tokens** (`overlap`) of the one
before it. The cut rules are the character splitter's (`conformance/chunk.json`) measured in tokens:
the window is the longest stretch of at most `size` tokens; the cut is just after a paragraph
break, else a line break, else a sentence's `. `, looked for in the window's last third (by
characters), else at the window's end; the next piece begins at the start of the token `overlap`
tokens before the cut. Pieces under 40 characters are dropped; a text that fits is one piece.

Tokens are counted with the embedder's own tokenizer where the server says how (llama.cpp's
`/tokenize`, for one). Where it does not, a count of `ceil(UTF-8 bytes / 2)` stands in — an
estimate, not a bound: it has not been measured against a real tokenizer. **A piece the embedder
still refuses for its length is split in two at the best cut and both are embedded; nothing is
dropped.**
`conformance/chunk_tokens.json` fixes the rules with a stand-in tokenizer (a token is a run of
non-whitespace), so both projects can be checked without an embedder.

## Instruction files, stacked

Instruction files are **collected from the boundary down to the start directory, outermost first**:
every directory on the way may contribute one, and all of them go to the model — the root's, then a
section's, then a repository's. (Before 3.0.0 the CLI took only the nearest one.)

- **The names**, in order of preference within one directory: `AGENTS.md`, then `CLAUDE.md`. A
  directory contributes the first of them that is a file the session can read; never both.
- **Only what the session can read is loaded.** A file at `none` — in a passage, or taken away under
  a granted directory — is not loaded, and the walk goes on below it: the next directory down may
  still contribute. A file granted on its own (`/AGENTS.md` ticked while `/` is not) is loaded.
- A start directory outside the boundary is read as the boundary.
- On a device the boundary is the project root, a file counts only when it really is a file inside
  the project (a link to elsewhere is not read), and the CLI's global `AGENTS.md` comes before the
  chain, the `instructions` named in its configuration after it.
- **Below the start directory**, a file under a directory with its own instruction file hands the
  model that file the first time something under it is read, once per session (the CLI's "nearby
  instructions"), by the same reading rules.
- Each is given to the model under its path relative to the boundary.

`conformance/instructions.json` gives the cases, including the passage.

## Skills

A skill is a directory with a `SKILL.md` (frontmatter `name`, `description`), and `skills_list`,
`skill_view` and `skill_manage` are its meaning over files on both sides: the index in the prompt
(`prompts/blocks/skills.md`), `skill_view` to load one, `skill_manage` to make or change one, which
checks the frontmatter, the name and the size; `edit` works on the file too. Neither side syncs
skills on its own.

**Where they are found**, in order of precedence — a name found in an earlier place wins, and the
later one is not offered:

| Side | Places, the most specific first |
|---|---|
| chat | the `skills/` directory of every directory from the start directory up to the boundary, the nearest first, **the root's excluded**; then the person's own `/home/<user>/skills/`; then the organisation's `/skills/` (a skills repository mounted there, or a plain directory) |
| device | the project's `.agent/skills/` (a trusted project); then the user's own skills directory; then the directories the configuration adds, in its order |

So on both sides the session's own place comes first, the person's next, what is shared last. Only
what the session can read is a skill there; `skill_manage` makes a new one in the person's own
place.

**A skill's name**, which `skill_manage` checks when it makes or renames one: lowercase letters,
digits and `-`, starting with a letter or a digit, at most 64 characters —
`^[a-z0-9][a-z0-9-]{0,63}$`, the Agent Skills format's rule. A `SKILL.md` made elsewhere whose name
does not fit is still offered when its name is one line of at most 64 characters; a name is looked
up ignoring case, with `_` and spaces read as `-`.

## Memory

Memory is **records, not files**, and **the server keeps them for both sides**: a chat's memory is
its data group's partition, and a device logged in to an instance reads and writes the same records
through the instance (`acp.md`, *The HTTP API*), for a session the web UI opened in that chat's data
group, and for a session of its own in the group of the session's model. The `memory` tool is the
same tool on both sides (`tools/memory.json`); what each offers of its targets is its `narrow`.