@awebai/oats 0.30.0 → 0.30.2

package/capabilities/oats-okf/schemas/okf-base.schema.json

@@ -1,46 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://oats.dev/schemas/okf-base.schema.json",
-  "type": "object",
-  "required": [
-    "version",
-    "id",
-    "nodes"
-  ],
-  "properties": {
-    "version": {
-      "const": 1
-    },
-    "id": {
-      "type": "string",
-      "pattern": "^(?!(?:constructor|__proto__|prototype|toString|valueOf)$)[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$"
-    },
-    "nodes": {
-      "type": "object",
-      "minProperties": 1,
-      "propertyNames": {
-        "type": "string",
-        "pattern": "^(?!(?:constructor|__proto__|prototype|toString|valueOf)$)[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$"
-      },
-      "additionalProperties": {
-        "type": "object",
-        "required": [
-          "path",
-          "owner"
-        ],
-        "properties": {
-          "path": {
-            "type": "string",
-            "minLength": 1
-          },
-          "owner": {
-            "type": "string",
-            "pattern": "^(?!(?:constructor|__proto__|prototype|toString|valueOf)$)[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$"
-          }
-        },
-        "additionalProperties": false
-      }
-    }
-  },
-  "additionalProperties": false
-}

package/capabilities/oats-okf/schemas/okf-bindings.schema.json

@@ -1,112 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://oats.dev/schemas/okf-bindings.schema.json",
-  "type": "object",
-  "required": [
-    "version",
-    "stateDir",
-    "bases"
-  ],
-  "properties": {
-    "version": {
-      "const": 1
-    },
-    "stateDir": {
-      "type": "string",
-      "minLength": 1
-    },
-    "cron": {
-      "type": "string",
-      "default": "*/15 * * * *",
-      "minLength": 1,
-      "pattern": "\\S"
-    },
-    "tz": {
-      "type": "string",
-      "default": "UTC",
-      "minLength": 1,
-      "pattern": "\\S"
-    },
-    "bases": {
-      "type": "object",
-      "minProperties": 1,
-      "propertyNames": {
-        "type": "string",
-        "pattern": "^(?!(?:constructor|__proto__|prototype|toString|valueOf)$)[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$"
-      },
-      "additionalProperties": {
-        "oneOf": [
-          {
-            "type": "object",
-            "required": [
-              "id",
-              "kind",
-              "path"
-            ],
-            "properties": {
-              "id": {
-                "type": "string",
-                "pattern": "^(?!(?:constructor|__proto__|prototype|toString|valueOf)$)[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$"
-              },
-              "kind": {
-                "const": "directory"
-              },
-              "path": {
-                "type": "string",
-                "minLength": 1
-              }
-            },
-            "additionalProperties": false
-          },
-          {
-            "type": "object",
-            "required": [
-              "id",
-              "kind",
-              "repository",
-              "root",
-              "acceptedBranch",
-              "pr"
-            ],
-            "properties": {
-              "id": {
-                "type": "string",
-                "pattern": "^(?!(?:constructor|__proto__|prototype|toString|valueOf)$)[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$"
-              },
-              "kind": {
-                "const": "git"
-              },
-              "repository": {
-                "type": "string",
-                "minLength": 1
-              },
-              "root": {
-                "type": "string",
-                "minLength": 1
-              },
-              "acceptedBranch": {
-                "type": "string",
-                "minLength": 1
-              },
-              "pr": {
-                "type": "object",
-                "required": [
-                  "repository"
-                ],
-                "properties": {
-                  "repository": {
-                    "type": "string",
-                    "pattern": "^[\\w.-]+/[\\w.-]+$"
-                  }
-                },
-                "additionalProperties": false
-              }
-            },
-            "additionalProperties": false
-          }
-        ]
-      }
-    }
-  },
-  "additionalProperties": false
-}

package/capabilities/oats-okf/schemas/okf-portable-declaration.schema.json

@@ -1,87 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://oats.dev/schemas/okf-portable-declaration.schema.json",
-  "title": "OATS OKF portable knowledge declaration",
-  "$defs": {
-    "identifier": {
-      "type": "string",
-      "pattern": "^(?!(?:constructor|__proto__|prototype|toString|valueOf)$)[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$"
-    },
-    "directory": {
-      "type": "object",
-      "required": ["id", "kind", "path"],
-      "properties": {
-        "id": {"$ref": "#/$defs/identifier"},
-        "kind": {"const": "directory"},
-        "path": {"type": "string", "pattern": "^path:/"}
-      },
-      "additionalProperties": false
-    },
-    "git": {
-      "type": "object",
-      "required": ["id", "kind", "repository", "root", "acceptedBranch", "pr"],
-      "properties": {
-        "id": {"$ref": "#/$defs/identifier"},
-        "kind": {"const": "git"},
-        "repository": {"type": "string", "pattern": "^(?!(?:https://[^/]*@|ssh://[^/@]*:[^/@]*@))(?:(?:https|ssh)://|git@)[^\\s?#]+$"},
-        "root": {"type": "string", "minLength": 1},
-        "acceptedBranch": {"type": "string", "minLength": 1},
-        "pr": {
-          "type": "object",
-          "required": ["repository"],
-          "properties": {"repository": {"type": "string", "pattern": "^[\\w.-]+/[\\w.-]+$"}},
-          "additionalProperties": false
-        }
-      },
-      "additionalProperties": false
-    },
-    "locator": {"oneOf": [{"$ref": "#/$defs/directory"}, {"$ref": "#/$defs/git"}]},
-    "store": {
-      "oneOf": [
-        {"type": "object", "required": ["fixed"], "properties": {"fixed": {"$ref": "#/$defs/locator"}}, "additionalProperties": false},
-        {"type": "object", "required": ["default"], "properties": {"default": {"$ref": "#/$defs/locator"}}, "additionalProperties": false},
-        {"type": "object", "required": ["inherit"], "properties": {"inherit": {"type": "string", "minLength": 1}}, "additionalProperties": false}
-      ]
-    }
-  },
-  "type": "object",
-  "required": ["contract", "version", "payload"],
-  "properties": {
-    "contract": {"const": "oats.okf.locations"},
-    "version": {"const": 1},
-    "payload": {
-      "type": "object",
-      "required": ["owner", "stores", "reads", "owns"],
-      "properties": {
-        "owner": {"$ref": "#/$defs/identifier"},
-        "stores": {
-          "type": "object",
-          "propertyNames": {"$ref": "#/$defs/identifier"},
-          "additionalProperties": {"$ref": "#/$defs/store"}
-        },
-        "reads": {
-          "type": "array",
-          "uniqueItems": true,
-          "items": {
-            "type": "object",
-            "required": ["store", "node"],
-            "properties": {"store": {"$ref": "#/$defs/identifier"}, "node": {"$ref": "#/$defs/identifier"}},
-            "additionalProperties": false
-          }
-        },
-        "owns": {
-          "type": "array",
-          "uniqueItems": true,
-          "items": {
-            "type": "object",
-            "required": ["node"],
-            "properties": {"node": {"$ref": "#/$defs/identifier"}, "destination": {"$ref": "#/$defs/identifier"}},
-            "additionalProperties": false
-          }
-        }
-      },
-      "additionalProperties": false
-    }
-  },
-  "additionalProperties": false
-}

package/capabilities/oats-okf/schemas/okf-portable-payload.schema.json

@@ -1,113 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://oats.dev/schemas/okf-portable-payload.schema.json",
-  "title": "OATS OKF effective portable binding payload",
-  "$defs": {
-    "identifier": {
-      "type": "string",
-      "pattern": "^(?!(?:constructor|__proto__|prototype|toString|valueOf)$)[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$"
-    },
-    "directory": {
-      "type": "object",
-      "required": ["id", "kind", "path"],
-      "properties": {
-        "id": {"$ref": "#/$defs/identifier"},
-        "kind": {"const": "directory"},
-        "path": {"type": "string", "pattern": "^/"}
-      },
-      "additionalProperties": false
-    },
-    "git": {
-      "type": "object",
-      "required": ["id", "kind", "repository", "root", "acceptedBranch", "pr"],
-      "properties": {
-        "id": {"$ref": "#/$defs/identifier"},
-        "kind": {"const": "git"},
-        "repository": {"type": "string", "pattern": "^(?!(?:https://[^/]*@|ssh://[^/@]*:[^/@]*@))(?:(?:https|ssh)://|git@)[^\\s?#]+$"},
-        "root": {"type": "string", "minLength": 1},
-        "acceptedBranch": {"type": "string", "minLength": 1},
-        "pr": {
-          "type": "object",
-          "required": ["repository"],
-          "properties": {"repository": {"type": "string", "pattern": "^[\\w.-]+/[\\w.-]+$"}},
-          "additionalProperties": false
-        }
-      },
-      "additionalProperties": false
-    },
-    "store": {"oneOf": [{"$ref": "#/$defs/directory"}, {"$ref": "#/$defs/git"}]},
-    "read": {
-      "type": "object",
-      "required": ["store", "node"],
-      "properties": {"store": {"$ref": "#/$defs/identifier"}, "node": {"$ref": "#/$defs/identifier"}},
-      "additionalProperties": false
-    },
-    "own": {
-      "type": "object",
-      "required": ["store", "node", "steward"],
-      "properties": {"store": {"$ref": "#/$defs/identifier"}, "node": {"$ref": "#/$defs/identifier"}, "steward": {"$ref": "#/$defs/identifier"}},
-      "additionalProperties": false
-    },
-    "reference": {
-      "type": "string",
-      "pattern": "^(?!(?:constructor|__proto__|prototype|toString|valueOf)/)[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}/(?!(?:constructor|__proto__|prototype|toString|valueOf)$)[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$"
-    }
-  },
-  "type": "object",
-  "required": ["owner", "stores", "reads", "owns", "runtime", "execution"],
-  "properties": {
-    "owner": {"$ref": "#/$defs/identifier"},
-    "stores": {
-      "type": "object",
-      "minProperties": 1,
-      "propertyNames": {"$ref": "#/$defs/identifier"},
-      "additionalProperties": {"$ref": "#/$defs/store"}
-    },
-    "reads": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/read"}},
-    "owns": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/own"}},
-    "runtime": {
-      "type": "object",
-      "required": ["descriptorFile", "bindings", "declaration"],
-      "properties": {
-        "descriptorFile": {"type": "string", "pattern": "^/"},
-        "bindings": {
-          "type": "object",
-          "required": ["version", "stateDir", "bases"],
-          "properties": {
-            "version": {"const": 1},
-            "stateDir": {"type": "string", "pattern": "^/"},
-            "bases": {
-              "type": "object",
-              "minProperties": 1,
-              "propertyNames": {"$ref": "#/$defs/identifier"},
-              "additionalProperties": {"$ref": "#/$defs/store"}
-            }
-          },
-          "additionalProperties": false
-        },
-        "declaration": {
-          "type": "object",
-          "required": ["version", "owner", "reads", "owns"],
-          "properties": {
-            "version": {"const": 1},
-            "owner": {"$ref": "#/$defs/identifier"},
-            "reads": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/reference"}},
-            "owns": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/reference"}}
-          },
-          "additionalProperties": false
-        }
-      },
-      "additionalProperties": false
-    },
-    "execution": {
-      "type": "object",
-      "required": ["runtime", "model"],
-      "properties": {
-        "runtime": {"oneOf": [{"const": "pi"}, {"const": "claude"}, {"const": "codex"}]},
-        "model": {"oneOf": [{"type": "null"}, {"type": "string", "minLength": 1}]}
-      },
-      "additionalProperties": false
-    }
-  },
-  "additionalProperties": false
-}

package/capabilities/oats-okf/schemas/okf-soul.schema.json

@@ -1,37 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://oats.dev/schemas/okf-soul.schema.json",
-  "type": "object",
-  "required": [
-    "version",
-    "owner",
-    "owns",
-    "reads"
-  ],
-  "properties": {
-    "version": {
-      "const": 1
-    },
-    "owner": {
-      "type": "string",
-      "pattern": "^(?!(?:constructor|__proto__|prototype|toString|valueOf)$)[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$"
-    },
-    "owns": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "pattern": "^(?!(?:constructor|__proto__|prototype|toString|valueOf)/)[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}/(?!(?:constructor|__proto__|prototype|toString|valueOf)$)[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$"
-      },
-      "uniqueItems": true
-    },
-    "reads": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "pattern": "^(?!(?:constructor|__proto__|prototype|toString|valueOf)/)[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}/(?!(?:constructor|__proto__|prototype|toString|valueOf)$)[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$"
-      },
-      "uniqueItems": true
-    }
-  },
-  "additionalProperties": false
-}

package/capabilities/oats-okf/skills/okf-consultation/SKILL.md

@@ -1,144 +0,0 @@
----
-name: okf-consultation
-description: >-
-  Consulting your soul's knowledge with the `oats okf` CLI: reading its
-  external OKF bases remotely at the accepted commit (index, cat, ls, links,
-  search, bases) with no local copy, then citing what you relied on. Use when
-  starting a task or resuming after compaction, when looking up a prior
-  decision, lesson or concept, when asked "what do we know about X" or to
-  "check the knowledge base", before re-deriving a design decision, when a
-  question touches your domain, or when an `oats okf` receipt says STALE or a
-  command errors. What to write in your own notes is the okf-instance-knowledge
-  skill.
----
-
-# Consulting your knowledge with `oats okf`
-
-Your soul's accumulated judgment — decisions and their rationale, lessons,
-rejected alternatives, limits — lives outside the soul, in external OKF
-**bases**. You read it remotely; nothing is copied into your home. Consulting
-it before you act is how you avoid re-deciding what was already decided.
-
-## The model
-
-- **Base / alias.** Each bound base has an alias (`oats okf bases` lists
-  them). A base is one OKF bundle and one link namespace.
-- **Node.** A subdirectory of a base with its own `index.md`. Your soul
-  **owns** some nodes (you are responsible for them) and **reads** others
-  (starting context). Neither is an access list: every bound base is readable.
-- **Accepted commit.** `oats okf` serves only a base's accepted state: the
-  accepted branch of a Git base, the in-place files of a directory base. An
-  open PR is not accepted knowledge until it is merged.
-- **Host cache, no local copy.** A Git base is read from one host-wide cache
-  that fetches file contents on first read. Your home has no `./knowledge/`
-  and no view directory. A `./knowledge/` left by okf 2.x is stale; ignore it.
-- **Receipts.** Every answer ends with `— alias@<short-oid> (fetched <age>)`.
-  With `--json`, the result carries `receipt: {base, kind, commit|digest,
-  fetchedAt, stale}`.
-
-Run every command from your instance home.
-
-## At the start of every task, and after compaction
-
-1. `oats okf index` prints your owned then read nodes' indexes, each headed
-   `## alias/node (owns|reads)`.
-2. Choose the entries relevant to *this* task by their one-line descriptions.
-3. `oats okf cat --base ALIAS /node/path.md` for each of those, and follow
-   their links only as far as the task needs (see Navigating).
-4. Write down in STATE.md which concepts shaped your plan, with their
-   citations.
-
-Do not skip this because the task looks small: prior decisions are cheapest
-to find before you have written the code that contradicts them.
-
-## Consult again while working
-
-The start-of-task read is not enough. Consult again:
-
-- **Before a design decision.** Search for the decision's subject, and read
-  any prior decision on it before choosing.
-- **Before re-deriving something.** If you are about to work out why
-  something is the way it is, search first; the rationale may be recorded.
-- **When a question touches your domain**, including a teammate's question.
-- **Before saying "we decided…" or "we tried…"**: cite it, or don't claim it.
-- **When something surprises you.** A lesson may already explain it.
-
-## Commands
-
-| Command | What it answers |
-| --- | --- |
-| `oats okf bases [--fresh]` | aliases, accepted commit, freshness, validity, your owns/reads |
-| `oats okf index [--base A] [NODE \| A/NODE]` | one node's `index.md`; no args: all your nodes; `--base A` alone: the base root index |
-| `oats okf cat --base A PATH [--from P]` | one Markdown file, in full |
-| `oats okf ls --base A [DIR]` | directory entries, each concept's `type` / `title` / `description` |
-| `oats okf links --base A PATH` | the file's outgoing links, resolved, `ok` / `MISSING` / `REFUSED` / `external` |
-| `oats okf search [--base A \| --all] [--node N] [--regex] [--case-sensitive] TEXT` | matching lines `{base, path, line, snippet}` |
-
-All take `--json`. `read` (the okf 2.x spelling of `cat`) is removed in 4.0.0
-(`E_REMOVED`): use `cat`.
-
-## Navigating
-
-Paths resolve like OKF links, **from the base root, not the filesystem**:
-
-- `/node/decisions/x.md` is base-root absolute (the usual form in indexes'
-  absolute links and in citations);
-- a relative link (`../lessons/y.md`, `decisions/x.md`) is relative to the file
-  it appeared in: pass that file as `--from`;
-- a bare `node/x.md` without `--from` resolves from the root.
-
-Worked example (a lesson linked from a decision):
-
-```sh
-oats okf index expert
-oats okf cat --base project /expert/decisions/retry-policy.md
-oats okf links --base project /expert/decisions/retry-policy.md
-oats okf cat --base project ../lessons/storm.md --from /expert/decisions/retry-policy.md
-```
-
-`links` shows every target already resolved, so you can `cat` the resolved
-path directly. `ls` is for choosing what to read from its descriptions, not
-for reading everything.
-
-## Searching
-
-`oats okf search TEXT` searches your nodes' bases (fixed string,
-case-insensitive, Markdown only), capped at 50 hits with "and N more". Narrow
-with `--node`, a longer phrase or `--base`; widen with `--all`. Search finds
-words, not meaning: when it finds nothing, try a synonym, then navigate from
-the index. A hit is a pointer: `cat` the concept before relying on it.
-
-## Citing
-
-Cite what you relied on as `alias/node/concept.md@<short-oid>`, using the oid
-from the receipt line (a directory base cites `alias@dir:<digest>`). Cite in
-STATE.md, notes/, PR descriptions and answers, so a reader knows which
-accepted state you saw.
-
-## Freshness
-
-Reads use the cached accepted commit while it is younger than the
-`consult-max-age` setting (default 300 s); after that the accepted branch is
-refetched first. `--fresh` refetches now (for example right after a PR
-merged). If a fetch fails, the last fetched accepted commit is still served,
-marked `stale: true` / `STALE:` with the reason: say so when it matters. With
-nothing cached and no network, the command fails with `E_BASE_UNAVAILABLE`:
-report it, and do not answer from memory or from an old `./knowledge/`.
-
-## Gotchas
-
-- Links resolve from the base root. `/node/x.md` is never a filesystem path,
-  and filesystem paths, `..` escapes, URLs, hidden paths and symlinks are
-  refused (`E_PATH`).
-- Never bulk-`cat` a whole node or loop `cat` over `ls` output. Index first,
-  then follow the few relevant links.
-- Don't edit knowledge. The write path is notes/ → the knowledge harvester →
-  a reviewed PR (or a directory publication). Write insights to notes/ (the
-  okf-instance-knowledge skill), not into a base.
-- `oats okf refresh` and `read` are gone (`E_REMOVED`): every read already sees the
-  accepted state.
-- `cat` reads `.md` files only (`E_NOT_MARKDOWN` otherwise); `E_NOT_FOUND`
-  lists the nearest directory's entries to try instead.
-
-Read [references/consult.md](references/consult.md) for more search examples,
-the error table and freshness edge cases.

package/capabilities/oats-okf/skills/okf-consultation/references/consult.md

@@ -1,86 +0,0 @@
-# okf-consultation — reference detail
-
-The okf-consultation skill's detail. Read this when navigating links, when a search is noisy or empty, when a
-receipt says `STALE`, or when a command errors. Run every command from your
-instance home (`oats okf …` resolves your registered source there).
-
-## Navigation, worked example
-
-Task: "change how retries back off". Your soul owns `project/expert`.
-
-```sh
-oats okf index                      # ## project/expert (owns) … ## project/peer (reads)
-#   * [Retry policy](decisions/retry-policy.md) - Why retries back off exponentially.
-oats okf cat --base project /expert/decisions/retry-policy.md
-#   … "superseded the fixed delay; see [the incident](../lessons/fixed-delay-storm.md)"
-oats okf links --base project /expert/decisions/retry-policy.md
-#   ok        /expert/lessons/fixed-delay-storm.md  (../lessons/fixed-delay-storm.md)
-#   MISSING   /expert/decisions/jitter.md
-oats okf cat --base project ../lessons/fixed-delay-storm.md \
-  --from /expert/decisions/retry-policy.md
-```
-
-- `index` with a node name (`oats okf index expert` or `project/expert`) prints
-  one index; `--base A` alone prints the base's root `index.md`.
-- A link in a concept is relative to **that concept's directory**: pass the
-  concept as `--from`, or use `links` to see every target already resolved.
-- `/node/x.md` is always from the base root; a bare `node/x.md` without
-  `--from` is also from the root.
-- `ls --base A /node/decisions` shows each concept's `type`, `title` and
-  `description` — use it to pick what to `cat`, not to read everything.
-- `MISSING` in `links` is a dangling link (allowed by OKF; not an error).
-  `REFUSED` is a link that would leave the base or is malformed.
-
-## Search
-
-```sh
-oats okf search "backoff"                     # your nodes' bases, case-insensitive
-oats okf search --node expert "jitter"        # one of your nodes
-oats okf search --base project --node peer "rate limit"
-oats okf search --all "idempotency"           # every bound base
-oats okf search --regex "retr(y|ies)"         # opt-in regex
-```
-
-- Fixed string, case-insensitive by default (`--case-sensitive` to change);
-  `--regex` is extended regex in Git bases, JavaScript RegExp in directory ones.
-- Only `.md` files inside the base root; results are `{base, path, line,
-  snippet}`, capped at 50 with "and N more" — narrow with `--node` or a longer
-  phrase rather than paging.
-- Search finds words, not meaning: when it's empty, try a synonym, then
-  navigate from the index. A hit is a pointer; `cat` the concept before
-  relying on it.
-- Git bases search with `git grep` at the accepted commit (the first search of
-  a node fetches its blobs in one batch); directory bases walk the files in
-  place, bounded to 20000 files.
-
-## Citing
-
-Cite what you relied on as `alias/node/concept.md@<short-oid>`, the oid from
-the receipt line (`— project@1a2b3c4d5e6f (fetched 2m ago)`). A directory base
-cites its digest (`project@dir:9f8e…`). Cite in notes/, PR descriptions and
-answers so a reader can see which accepted state you saw.
-
-## Freshness
-
-- Reads use the host cache's accepted commit if it was fetched within
-  `consult-max-age` seconds (setting, default 300); older, the accepted branch
-  is fetched first. `--fresh` fetches now. Neither ever selects another
-  branch or commit: only the accepted one is served.
-- Fetch failed (offline, auth, timeout): the last fetched accepted commit is
-  served with `stale: true` and the reason in the receipt (`STALE:` in text).
-  Say so if it matters to your answer; retry later with `--fresh`.
-- No cached commit and no network → `E_BASE_UNAVAILABLE`: report it, don't
-  guess from memory or from an old `./knowledge/`.
-- Merged a PR a minute ago? `--fresh` sees it once it is on the accepted branch.
-
-## Errors
-
-| Code | Meaning / what to do |
-| --- | --- |
-| `E_BASE_UNKNOWN` | alias not bound; the message lists the bound aliases (`oats okf bases`) |
-| `E_NOT_FOUND` | no such file at the accepted commit; the message lists the nearest directory |
-| `E_NOT_MARKDOWN` | `cat` reads `.md` concepts only; use `ls` for a directory |
-| `E_PATH` | escapes the base root, filesystem path, URL, hidden path, symlink or submodule |
-| `E_RECOVERY` | a directory-base publication is pending; retry after it completes |
-| `E_BASE_UNAVAILABLE` | the base can't be read and nothing is cached; report it |
-| `E_REMOVED` | `refresh` and `read` no longer exist; use `index` / `cat` |