omgbase 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,199 @@
+# omgbase — the `omg` CLI
+
+`omg` (also installed as `omgbase`) is the command-line client for **Open Markdown Graph Base**: a versioned, addressable graph layer over a directory of Markdown/YAML/JSON files. Your files stay the human source of truth; an embedded SQLite database under `.omgbase/` owns block identity, history, links, and the indexes you query. The CLI is the engine's second client — a thin adapter over [`@omgbase/core`](https://github.com/omgbase/omgbase/tree/main/packages/core), **embedded and daemonless**: every command opens the database directly, does its work in-process, and exits. Design notes live in the [monorepo README](https://github.com/omgbase/omgbase#readme) and [`docs/cli.md`](https://github.com/omgbase/omgbase/blob/main/docs/cli.md).
+
+## Install
+
+```bash
+npm install -g omgbase              # the `omg` and `omgbase` binaries (Node >= 22)
+npm install -g @omgbase/embedder    # optional: local semantic search
+```
+
+`@omgbase/embedder` provides `omgbase-embedder`, a local transformers.js model (`Xenova/gte-base`, 768-dim) spoken to over stdio, so the CLI itself carries no ML dependency. Without it, full-text search, queries, and edits all work; `omg find` and OQX `semantic("…")` just have no embedding index to rank by. `omg init` offers to configure it when it is on `PATH`, or set it later with `omg config set embedding.provider omgbase-embedder --repo ""`.
+
+## Five-minute tour
+
+A throwaway directory with two Markdown files, `README.md` (a heading, a task list, a `[[decisions]]` link) and `decisions.md` (frontmatter plus two ADR headings). Every transcript below is real output.
+
+```console
+$ omg init
+  not inside a git repo — no .gitignore needed for .omgbase/
+  omgbase  >  initialized
+  ----------------------------------------
+  ok workspace  /private/tmp/omg-tour/notes
+  next: omg source add . to point a repo at a directory of files
+
+$ omg source add . -y
+  * notes ← /private/tmp/omg-tour/notes  2 files
+
+$ omg status
+  omgbase  >  notes
+  /private/tmp/omg-tour/notes
+  ----------------------------------------
+  [D] docs  2             watcher o none
+  [B] blocks  13          synced  ok converged
+  * commits  2            queue   empty
+  > edges  1              commit# 2
+
+$ omg ls
+README.md     8 blocks  0s ago
+decisions.md  5 blocks  0s ago
+```
+
+`init` creates the workspace and ingests nothing; `source add` points a repo at a directory (the repo takes the directory's name) and runs the initial sync. Now find and query:
+
+```console
+$ omg find sqlite
+b_v32ar6f  decisions.md#heading[3]  ADR-002 Embedded SQLite
+
+$ omg q 'from blocks where type == "task" && !attrs.checked'
+b_24nr0y0  README.md
+b_36p2zw1  README.md
+
+$ omg q '$repo.blocks count { where type == "task" && !attrs.checked }'
+2
+
+$ omg outline README.md
+  omgbase  >  README.md
+  ----------------------------------------
+b_7046e9t h1   Project notes  §
+b_y9cqtgq p    A small vault to try out omgbase.
+b_e1x1y8p h2   Launch  §
+b_zysh41w ul
+  b_36p2zw1 li   ☐ Write the announcement
+  b_24nr0y0 li   ☐ Ship the release
+  b_1nrsgvf li   ☑ Pick a date
+b_1w4t737 p    See [[decisions]] for the why.
+
+$ omg cat b_v32ar6f --resolution text
+ADR-002 Embedded SQLite
+```
+
+`omg cat <path>` prints a document's exact bytes (frontmatter and all); given a block id it prints that block. Edits are structural mutations that update the file and the database together. The pipe is the changeset boundary — `--ids` emits block ids, `done -` reads them from stdin and completes them in one commit:
+
+```console
+$ omg q 'from blocks where type == "task" && !attrs.checked' --ids | omg done -
+  ok committed · 1 document touched
+b_24nr0y0
+b_36p2zw1
+
+$ omg append b_e1x1y8p -m 'Shipped on time.'
+  ok committed · 1 document touched
+b_qb861mj
+
+$ omg cat README.md | tail -3
+See [[decisions]] for the why.
+
+Shipped on time.
+
+$ omg log
+#1 observed observed: README.md — 8 inserted
+#2 observed observed: decisions.md — 5 inserted
+#3 api      api(human:alice): README.md — 8 edited
+#4 api      api(human:alice): README.md — 8 edited, 1 inserted
+```
+
+Every edit is a commit; `omg hist <block>` is one block's biography and `omg diff <doc>` a unified diff. More worked examples (a larger corpus, the OQX tutorial, the interactive shell) are under [`examples/`](https://github.com/omgbase/omgbase/tree/main/examples).
+
+## Command catalog
+
+Grouped exactly as `omg --help` prints them; `omg <command> --help` gives one uniform card per command.
+
+**bootstrap**
+- `init` — Create a workspace (run `source add` to ingest files)
+- `source` — Where a repo's bytes come from (add/list/attach/detach/rm)
+- `repos` — List repos in this workspace
+
+**orient & read**
+- `status` — Where am I: repo, sync, watcher, queue
+- `ls` — List live documents
+- `outline`, `ol` — Document outline (frozen wire format)
+- `cat` — Content bytes of a node (default raw)
+- `show` — Metadata card for a node
+- `find` — Ranked hybrid search for the id of a thing
+
+**query**
+- `query`, `q` — Composable query (OQX: from/where/select + collection ops)
+- `run` — Evaluate an ```` ```omg ```` fence (OQX, inert, read-only)
+
+**history & links**
+- `log` — Commit digests (change feed)
+- `hist` — A block's change biography
+- `diff` — Unified diff of a document
+- `links` — Open edges touching a node
+
+**mutate**
+- `apply` — Apply a raw changeset (the primitive)
+- `insert` — Insert blocks under a parent
+- `update` — Replace a block, or reconcile a whole document (identity-preserving)
+- `edit` — Edit a block in `$EDITOR` (CAS pinned)
+- `move` — Move blocks under a new parent
+- `rm` — Remove blocks (or `--doc` a document)
+- `done` — Check/uncheck task blocks
+- `append` — Append into a heading's section
+- `retarget` — Rewrite a link target (plan-by-default)
+- `split` — Split a block at offsets
+- `merge` — Merge adjacent blocks
+- `node` — Edit a node's editable properties (surgical)
+
+**documents**
+- `new` — Create a document
+- `mv` — Rename a document
+- `meta` — Patch a document's frontmatter
+
+**session**
+- `shell` — Persistent session with typed bindings (`@1`/`@_`/`@name`)
+
+**sync & serve**
+- `sync` — Reconcile a repo with its filesystem source (`--watch` to stay live; `--server` for remote)
+- `mcp` — Serve the MCP tool surface on stdio
+
+**admin**
+- `rebuild-index` — Rebuild derived tables
+- `gc` — Mark-and-sweep (flag-gated)
+- `doctor` — Invariant sweep (CI-able)
+- `config` — Read/write repo settings
+- `embed` — Embedding queue: status, or drain to embed
+
+## MCP server
+
+`omg mcp` serves the full engine tool surface over stdio with an in-process file watcher, so an agent session stays fresh; the host owns the process lifetime. Hosts launch servers from their own cwd, so point `-C` at an initialized workspace (a directory at or below one containing `.omgbase/`). Run outside a workspace it fails with `repo_not_found` and prints the `-C` form to use.
+
+Claude Code:
+
+```bash
+claude mcp add omg -- omg mcp -C /path/to/vault
+```
+
+Claude Desktop (`claude_desktop_config.json`), Cursor (`.cursor/mcp.json`), and any host that takes an `mcpServers` map:
+
+```json
+{ "mcpServers": { "omg": { "command": "omg", "args": ["mcp", "-C", "/path/to/vault"] } } }
+```
+
+Add `--repo <slug>` to `args` when the workspace holds several repos, and `--no-watch` to skip the in-process watcher (it is auto-off when another live watcher already holds the lease).
+
+## Remote mode
+
+The global `--server <cmd|url>` flag runs the same command against a **remote engine over MCP** instead of the embedded local store: an `http(s)://` value connects over Streamable HTTP (add headers with repeatable `-H "Name: value"`), anything else is a command spawned and spoken to over stdio, e.g. `omg --server "omg mcp -C /path/to/vault" ls`. Implemented for the reads `sync`, `query`, `outline`, `hist`, `cat`, `ls`, `diff`, `find`, `log`; the doc-level mutators `new`, `mv`, `meta`, `rm`, `update`, `retarget`; the block-level sugar `apply`, `insert`, `move`, `split`, `merge`, `done`, `append`, `node`; and `shell`. Other commands (`status`, `edit`, `init`, `source`, admin) reject `--server` with a usage error rather than silently running locally.
+
+## Output contract
+
+Global flags are recognized anywhere on the line: `-C <dir>`, `--repo <slug>`, `--json`, `--jsonl`, `--ids`, `--stale`, `--no-color`, `--dry-run`, `--server <cmd|url>`, `-H <header>`, `--help`/`-h`, `--version`/`-V`.
+
+- Human output (default) is colorized on a TTY; `--no-color`, `NO_COLOR`, or a pipe degrades to plain text.
+- Query hits (`omg q`, `omg run`) print as `<id>  <path>` lines. When the query projects (`select …`), they print as an aligned table instead: a dim header row, the id first, then the path (unless the projection itself selects `$path`), then the projected columns in `select` order. Strings and numbers are verbatim, an absent field is an empty cell, and a nested list/record is compact JSON clipped at 60 characters with `…`; `--jsonl` has the full values.
+- `--json` prints the library's result object verbatim as one JSON document (the same shape the MCP tools return). `--jsonl` flattens list results to one object per line; `--ids` prints bare ids/paths, one per line — pipe fuel for `omg cat -`, `omg show -`, `omg done -`.
+- `--dry-run` is global across every mutator: full validation and render, diffs printed, nothing committed.
+- Errors always go to stderr: `error[<code>]: <message>` plus any conflict payload, or the typed error object as JSON with `--json`.
+- Truncated list results print `… truncated; continue with --cursor <c>` on stderr and still exit 0.
+
+Exit codes: `0` success (including truncated); `1` typed engine error or conflict; `2` CLI usage error (unknown command or flag, missing argument, `--server` on an unsupported command).
+
+## Freshness
+
+Reads are current by default: before running, a command sweeps the repo's files for changes since the last ingest and re-ingests what moved (tens of milliseconds when nothing changed). Skip the sweep with `--stale`, or run `omg sync --watch` — a live watcher holds a lease on `.omgbase/watch.lock`, and commands that see a live lease skip the sweep. `omg status` reports `watcher: live` or `none`.
+
+## License
+
+MIT

package/dist/src/cmd/_remote.d.ts

@@ -1,4 +1,11 @@
+import { type EngineSpec } from "@omgbase/sync";
 import type { Cli } from "../context.js";
+/** Classify the global `--server` (+ `-H`) flags into an `EngineSpec`: an
+ *  http(s) URL → Streamable HTTP with the headers attached; anything else → a
+ *  command to spawn over stdio (a URL is never spawned). Usage errors — an empty
+ *  value, `-H` with a stdio command — are `CliUsageError` (exit 2). Pure:
+ *  nothing is connected or spawned here. */
+export declare function remoteSpec(cli: Cli): EngineSpec;
 /** Call an MCP tool on the remote engine, threading the global `--repo` slug.
  *  Returns the tool's parsed JSON result (same shape the local core fn returns,
  *  so the command's existing renderer works unchanged). */

package/dist/src/cmd/_remote.js

@@ -1,4 +1,4 @@
-import { connectStdioEngine, connectHttpEngine } from "@omgbase/sync";
+import { connectEngine, parseEngineSpec } from "@omgbase/sync";
 import { CliUsageError } from "../output.js";
 // Remote (`--server`) mode plumbing (ADR-014). When a command runs with the
 // global `--server <cmd|url>` flag, it reaches a remote engine over MCP instead
@@ -8,7 +8,10 @@ import { CliUsageError } from "../output.js";
 // closed via `closeRemote` at the end of a one-shot command or on shell exit.
 //
 // The flag is an http(s) URL to reach a remote server over Streamable HTTP, or
-// otherwise a command to spawn and talk to over stdio.
+// otherwise a command to spawn and talk to over stdio. That one rule lives in
+// `@omgbase/sync`'s `parseEngineSpec`; `remoteSpec` below is its CLI face, and
+// every `--server` consumer goes through it — including `sync`, which hands the
+// spec to `runFsMirror` instead of calling tools itself.
 let engine = null;
 /** The process's remote engine, connecting (spawning the command or opening the
  *  HTTP transport) on first use. `--repo` is threaded into each tool call by
@@ -16,19 +19,23 @@ let engine = null;
 async function remoteEngine(cli) {
     if (engine)
         return engine;
+    engine = await connectEngine(remoteSpec(cli));
+    return engine;
+}
+/** Classify the global `--server` (+ `-H`) flags into an `EngineSpec`: an
+ *  http(s) URL → Streamable HTTP with the headers attached; anything else → a
+ *  command to spawn over stdio (a URL is never spawned). Usage errors — an empty
+ *  value, `-H` with a stdio command — are `CliUsageError` (exit 2). Pure:
+ *  nothing is connected or spawned here. */
+export function remoteSpec(cli) {
     const spec = (cli.flags.server ?? "").trim();
-    if (/^https?:\/\//i.test(spec)) {
-        const headers = parseHeaders(cli.flags.headers);
-        engine = await connectHttpEngine({ url: spec, ...(Object.keys(headers).length > 0 ? { headers } : {}) });
-        return engine;
-    }
-    if (cli.flags.headers?.length)
+    const headers = parseHeaders(cli.flags.headers);
+    const isUrl = /^https?:\/\//i.test(spec);
+    if (!isUrl && Object.keys(headers).length > 0)
         throw new CliUsageError("-H/--header only applies to an http(s) --server url");
-    const argv = spec.split(/\s+/).filter(Boolean);
-    if (argv.length === 0)
+    if (spec.length === 0)
         throw new CliUsageError("--server requires a command to spawn (e.g. --server \"omg mcp -C /vault\") or an http(s) URL");
-    engine = await connectStdioEngine({ command: argv[0], args: argv.slice(1) });
-    return engine;
+    return parseEngineSpec(spec, headers);
 }
 /** Parse repeatable `-H "Name: value"` flags into a header map. Splits on the
  *  first colon; later values win for a repeated name. */

package/dist/src/cmd/cat.js

@@ -3,11 +3,19 @@ import { resolveRef, nodesGet, docsRead } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
 import { remoteCall } from "./_remote.js";
 import { expandBlockArgs } from "./_mutate.js";
+/** `--resolution` only means something for a block; say so (stderr) rather than
+ *  silently handing back raw bytes as if the flag had applied. */
+function warnDocResolution(cli, ref, resolution) {
+    if (resolution === "raw")
+        return;
+    cli.io.err(cli.style.warn(`  --resolution ${resolution} ignored for ${ref}: a document is always its exact bytes (resolutions apply to block refs)`));
+}
 async function catOne(cli, ref, resolution) {
     // Remote: the polymorphic `read_ref` tool classifies + reads server-side.
     if (cli.flags.server) {
         const r = await remoteCall(cli, "read_ref", { ref, ...(resolution !== "raw" ? { resolution } : {}) });
         if (r.kind === "document") {
+            warnDocResolution(cli, ref, resolution);
             return { text: String(r.content ?? ""), json: { doc: r.docId, path: r.path, content: r.content }, capture: r.content };
         }
         return { text: String(r.raw ?? r.text ?? r.label ?? ""), json: r, capture: r };
@@ -26,6 +34,7 @@ async function catOne(cli, ref, resolution) {
         const res = docsRead(ws.store, resolved.docId);
         if (!res)
             throw new EngineErrorLike("doc_missing", `no document ${ref}`);
+        warnDocResolution(cli, ref, resolution);
         // shell: the bytes (a string; @_ only)
         return { text: res.content, json: { doc: res.docId, path: res.path, content: res.content }, capture: res.content };
     }
@@ -47,9 +56,9 @@ async function runCat(cli, args) {
             summary: "Content bytes of a node — exact raw bytes by default, pipe-clean (`show` is the metadata card)",
             usage: "cat <node…|-> [--resolution raw|text|outline|skeleton|full]",
             options: [
-                ["<node…>", "one or more refs: a doc/block id, a path, or a locator (`notes/x.md#Risks/p[2]`)"],
+                ["<node…>", "one or more refs: a block id (`b_…`), a doc id (`d_…`), a node id (`n_…`), or a repo-relative doc path (`notes/x.md`)"],
                 ["-", `read refs from stdin, one per line (\`${cli.prog} q … --ids | ${cli.prog} cat -\`)`],
-                ["--resolution <r>", "raw (default: exact bytes) | text | outline | skeleton | full"],
+                ["--resolution <r>", "block refs only: raw (default: exact bytes) | text | outline | skeleton | full; a document is always its exact bytes (warns if given)"],
             ],
         });
     }

package/dist/src/cmd/oqx.js

@@ -1,7 +1,7 @@
 import { parseArgs } from "node:util";
 import { readFileSync } from "node:fs";
 import { oqxRun, oqxRunAsync, collectSemanticPhrases } from "@omgbase/core";
-import { truncationFooter, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { truncationFooter, EngineErrorLike, EXIT_OK, renderHelp, renderHits } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
 import { remoteCall } from "./_remote.js";
 import { readStdin } from "./_mutate.js";
@@ -10,12 +10,13 @@ import { readStdin } from "./_mutate.js";
 // belong to OQX (`<receiver> collect|exists|count|first|single { <block> }`).
 // `from E` selects + flattens a relation relative to the current source scope
 // (top-level `from docs` = the repository's docs; `$repo.docs collect { from
-// nodes … }` re-projects each doc through its nodes). Inside a block the
-// `where`/`select` keyword may be omitted: a leading predicate-shaped expression
-// is an implicit `where` (`nodes exists { kind == "md:task" }`), a bare
-// reference / `name: value` list is an implicit `select` (`nodes collect
-// { attrs.text }`); a bare boolean property still projects (filter with
-// `where active` or `active == true`). Features: a boolean where
+// nodes … }` re-projects each doc through its nodes). Clause order is fixed
+// (ADR-020): `select … from … where … follow … order by … limit … offset …`,
+// each at most once, at the top level and inside every block. Only `select` may
+// drop its keyword, and only as the first clause (`nodes collect { attrs.text }`
+// projects); a predicate always needs `where` (`nodes exists { where kind ==
+// "md:task" }`), so a bare boolean property projects rather than filters.
+// `where` may use the body's select aliases. Features: a boolean where
 // tree over scalar predicates and consumer directives, count comparisons
 // (`nodes count { … } >= 2`), nestable collect, one-scope lifts (^name:) that
 // filter + capture, one-scope-outward references (^name) that correlate a nested
@@ -28,8 +29,9 @@ import { readStdin } from "./_mutate.js";
 // `$repo.docs count { … }` / `$repo.docs exists { … }` reduce to a scalar,
 // `$repo.docs first { … }` / `$repo.docs single { … }` to zero-or-one row (bare
 // `from …` = collect). Coexists with `omg q` (CEL). Source is a positional
-// string or -f file|-. Human output: one hit per line (id + path), or the scalar
-// for count/exists; --json/--jsonl/--ids.
+// string or -f file|-. Human output: one hit per line (id + path), or an aligned
+// id/path/columns table when the query projects (`select`), or the scalar for
+// count/exists/none (see output.ts renderHits); --json/--jsonl/--ids.
 async function runOqx(cli, args) {
     const { values, positionals } = parseArgs({
         args,
@@ -60,25 +62,24 @@ async function runOqx(cli, args) {
             ],
         });
         cli.io.out("  e.g. query 'from docs where nodes count { where kind == \"md:task\" } >= 2'");
-        cli.io.out("       query 'from nodes where kind == \"md:section\" select items: section.blocks collect { where type == \"list_item\" }'");
-        cli.io.out("       query 'from docs where nodes collect { ^open: value where kind == \"md:task\" && !attrs.checked } select $path, open'");
-        cli.io.out("       query 'from docs select owner_id, owner: $repo.nodes single { where kind == \"person\" && attrs.id == ^owner_id }'");
+        cli.io.out("       query 'select items: section.blocks collect { where type == \"list_item\" } from nodes where kind == \"md:section\"'");
+        cli.io.out("       query 'select $path, open from docs where nodes collect { ^open: value where kind == \"md:task\" && !attrs.checked }'");
+        cli.io.out("       query 'select owner_id, owner: $repo.nodes single { where kind == \"person\" && attrs.id == ^owner_id } from docs'");
         cli.io.out("       query '$repo.docs count { where layer == \"canon\" }'   # scalar; also $repo.<target> exists/none/first/single { … }");
         cli.io.out("       query 'from docs where nodes none { where kind == \"md:task\" && !checked }'   # none = zero rows (≡ !exists; \"every\" = none over the complement)");
         cli.io.out("       query 'from docs where type == \"practitioner\" order by era desc limit 2 offset 1'   # limit/offset bound the set (after order/distinct, before the consumer)");
-        cli.io.out("       query 'from docs where $path == \"x.md\" select fm: entries(frontmatter) collect { k: $key, v: $value }'   # a record as a collection ($key/$value); also entries(attrs), entries(inline)");
-        cli.io.out("       query 'from docs where layer == \"canon\" select $path values'   # `values`: bare values, no {id,path} hits (one item only)");
-        cli.io.out("       query 'from docs select $path, tags: tags collect { $value values where $value != \"draft\" }'   # $value = the current item (here: each tag)");
+        cli.io.out("       query 'select fm: entries(frontmatter) collect { k: $key, v: $value } from docs where $path == \"x.md\"'   # a record as a collection ($key/$value); also entries(attrs), entries(inline)");
+        cli.io.out("       query 'select $path values from docs where layer == \"canon\"'   # `values`: bare values, no {id,path} hits (one item only)");
+        cli.io.out("       query 'select $path, tags: tags collect { $value values where $value != \"draft\" } from docs'   # $value = the current item (here: each tag)");
         cli.io.out("       query '$repo.docs collect { from nodes where kind == \"md:task\" }'   # `from E` re-projects the source (→ nodes)");
         cli.io.out("       query 'from docs where text(\"philosophers stone\") && layer == \"canon\"'   # full-text prune");
-        cli.io.out("       query 'from blocks where semantic(\"the great work\") > 0.6 select s: semantic(\"the great work\")'  # embedding score (needs a provider)");
+        cli.io.out("       query 'select s: semantic(\"the great work\") from blocks where semantic(\"the great work\") > 0.6'  # embedding score (needs a provider)");
         cli.io.out("       query 'from docs where type == \"practitioner\" order by era desc'   # order by <expr> [asc|desc]");
-        cli.io.out("       query 'from blocks where $id == \"b_x\" select t: text, d: $depth, s: $stop follow block.children'   # recursive walk ($depth/$stop metadata)");
+        cli.io.out("       query 'select t: text, d: $depth, s: $stop from blocks where $id == \"b_x\" follow block.children'   # recursive walk ($depth/$stop metadata)");
         cli.io.out("       query 'from nodes where name == \"Overview\" follow section.subsections { depth 3 }'   # follow [distinct] <rel> [{ where … frontier … depth n by … }]");
-        cli.io.out("       query 'from docs where $path == \"index.md\" select p: $path, d: $depth, s: $stop follow doc.out'   # citation graph (cyclic-safe: $stop=cycle)");
+        cli.io.out("       query 'select p: $path, d: $depth, s: $stop from docs where $path == \"index.md\" follow doc.out'   # citation graph (cyclic-safe: $stop=cycle)");
         cli.io.out("       query 'from blocks where type == \"list_item\" && $leaf follow block.children'   # $leaf/$depth/$stop filter the walk result post-walk");
-        cli.io.out("       query 'from edges where predicate == \"depends_on\" select src: $src, to: $dst_path'   # the edges target: predicate/provenance/dst_kind + $src/$dst_path/$dst_uri");
-        cli.io.out("       query 'from docs where $path == \"a.md\" follow doc.out { via predicate == \"cites\" }'   # predicate-filtered traversal (via = the licensing edge)");
+        cli.io.out("       query 'select src: $src, to: $dst_path from edges where predicate == \"depends_on\"'   # the edges target: predicate/provenance/dst_kind + $src/$dst_path/$dst_uri");
         return EXIT_OK;
     }
     const source = values.file
@@ -174,9 +175,7 @@ async function runOqx(cli, args) {
         io.err(style.dim("  no hits"));
         return EXIT_OK;
     }
-    for (const h of result.hits) {
-        io.out(`${style.id(h.id)}  ${style.accent(h.path)}`.trimEnd());
-    }
+    renderHits(cli, result.hits);
     if (result.truncated)
         truncationFooter(io, style, result.cursor ?? "");
     return EXIT_OK;

package/dist/src/cmd/run.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
 import { resolveRef, findDoc, loadDocBlocks, blockRaw, oqxRun, oqxRunAsync, collectSemanticPhrases } from "@omgbase/core";
-import { CliUsageError, EngineErrorLike, truncationFooter, EXIT_OK, renderHelp } from "../output.js";
+import { CliUsageError, EngineErrorLike, truncationFooter, EXIT_OK, renderHelp, renderHits } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
 // `omg run <locator|path>` (11 §5.3) — evaluate the first ```omg fence in a doc
 // (or the fence at a block locator) and print its results. The fence body is an
@@ -123,10 +123,9 @@ async function runRun(cli, args) {
         io.err(style.dim("  no hits"));
         return EXIT_OK;
     }
-    for (const h of result.hits) {
-        const preview = typeof h.text === "string" ? String(h.text).split("\n")[0] : "";
-        io.out(`${style.id(h.id)}  ${style.accent(h.path)}  ${preview}`.trimEnd());
-    }
+    // Same renderer as `omg query`: `<id>  <path>` lines, or a column table when
+    // the fence projects (a selected `text` shows as its first line).
+    renderHits(cli, result.hits);
     if (result.truncated)
         truncationFooter(io, style, result.cursor ?? "");
     return EXIT_OK;

package/dist/src/cmd/show.js

@@ -33,7 +33,7 @@ function runShow(cli, args) {
             summary: "Metadata card for a node: attrs, placement, open edges, last change (`cat` is the bytes)",
             usage: "show <node…|-> [--include history]",
             options: [
-                ["<node…>", "one or more refs: a doc/block id, a path, or a locator"],
+                ["<node…>", "one or more refs: a block id (`b_…`), a doc id (`d_…`), a node id (`n_…`), or a repo-relative doc path"],
                 ["-", `read refs from stdin, one per line (\`${cli.prog} q … --ids | ${cli.prog} show -\`)`],
                 ["--include <list>", "comma-separated extras; `history` adds the block's last 5 changes"],
             ],

package/dist/src/cmd/source.js

@@ -19,7 +19,7 @@ function help(cli) {
         summary: "Where a repo's bytes come from (a filesystem directory today; git/S3/… via adapters later)",
         usage: "source <add|list|attach|detach|rm> …",
         options: [
-            ["add <dir> [--slug <s>] [--name <n>] [-y]", "point a repo at a directory: creates the repo + runs the initial sync (-y skips the consent prompt)"],
+            ["add <dir> [--repo <slug>] [--name <n>] [-y]", "point a repo at a directory: creates the repo (named after the dir unless --repo) + runs the initial sync (-y skips the consent prompt)"],
             ["list", "list sources and which repos they feed"],
             ["attach <name> [--repo <slug>]", "attach an existing source to a repo"],
             ["detach <name> [--repo <slug>]", "detach a source from a repo"],
@@ -82,7 +82,7 @@ async function runAdd(cli, args) {
     const { values, positionals } = parseArgs({
         args,
         allowPositionals: true,
-        options: { slug: { type: "string" }, name: { type: "string" }, yes: { type: "boolean", short: "y" }, help: { type: "boolean" } },
+        options: { name: { type: "string" }, yes: { type: "boolean", short: "y" }, help: { type: "boolean" } },
     });
     if (values.help)
         return help(cli);
@@ -92,7 +92,10 @@ async function runAdd(cli, args) {
     const abs = resolve(cli.cwd, dir);
     if (!existsSync(abs) || !statSync(abs).isDirectory())
         throw new EngineErrorLike("target_missing", `no such directory: ${abs}`);
-    const slug = values.slug ?? (basename(abs) || "vault");
+    // `--repo <slug>` is the GLOBAL repo-selection flag (parsed in dispatch.ts, so it
+    // never reaches this parser); for `source add` the selected repo is the one being
+    // created/pointed, defaulting to the directory's name.
+    const slug = cli.flags.repo ?? (basename(abs) || "vault");
     const sourceName = values.name ?? `${slug}-fs`;
     const ws = cli.workspace();
     if (getSourceByName(ws.store, sourceName))

package/dist/src/cmd/sync.js

@@ -4,14 +4,18 @@ import { Watcher, WatchLease, EmbedDrainer, freshnessSweep, EngineError } from "
 import { runFsMirror } from "@omgbase/sync";
 import { EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
+import { remoteSpec } from "./_remote.js";
 import { openRepoSource } from "./_source.js";
 // `omg sync` — reconcile a repo with its filesystem source. One verb, three modes:
 //   omg sync                     one-shot local freshness sweep (fs → DB)
 //   omg sync --watch             stay live locally (external fs-adapter watcher)
-//   omg sync --server <cmd> …    the same, but against a remote engine over MCP
+//   omg sync --server <cmd|url>  the same, but against a remote engine over MCP
 //                                (the coordinator — mirrors `omgbase-sync`)
-// The `--server` form is the global remote flag (context REMOTE_OK); it shares
-// `runFsMirror` with the standalone `omgbase-sync` bin. There is no separate
+// The `--server` form is the global remote flag (context REMOTE_OK) and obeys
+// the same rule as every other remote command (`remoteSpec` in _remote.ts): an
+// http(s) URL is reached over Streamable HTTP (with `-H` headers); anything else
+// is a command spawned over stdio. It shares `runFsMirror` with the standalone
+// `omgbase-sync` bin. There is no separate
 // `omg watch` — watching is `omg sync --watch`. The local one-shot IS the
 // explicit form of the freshness sweep every read runs by default.
 function help(cli) {
@@ -21,8 +25,8 @@ function help(cli) {
         usage: ["sync [--watch]", 'sync --server <cmd|url> [-H "Name: value"]… [--root <dir>] [--out]'],
         options: [
             ["--watch", "stay live and reconcile edits as they land"],
-            ["--server <cmd|url>", "mirror a local directory into a remote engine over MCP (spawns <cmd>, or an http(s) url over Streamable HTTP)"],
-            ['-H "Name: value"', "(--server url) extra HTTP header, repeatable"],
+            ["--server <cmd|url>", "mirror a local directory into a remote engine over MCP: an http(s) url connects over Streamable HTTP; anything else is spawned as a stdio MCP server command"],
+            ['-H "Name: value"', "(--server url only) extra HTTP header, repeatable"],
             ["--root <dir>", "(--server) the directory to mirror (default cwd)"],
             ["--out", "(--server) also export engine-authored changes back to disk"],
         ],
@@ -38,11 +42,12 @@ async function runSync(cli, args) {
         return help(cli);
     // Remote mode: run the coordinator against an MCP server (shared with the
     // omgbase-sync bin). No local workspace needed — the fs dir is the source.
+    // `remoteSpec` classifies url-vs-command exactly as the other remote commands
+    // do, so an http(s) --server is connected to, never spawned as a command.
     if (cli.flags.server !== undefined) {
         const root = resolve(cli.cwd, values.root ?? ".");
-        const server = cli.flags.server.split(/\s+/).filter(Boolean);
         await runFsMirror({
-            server,
+            server: remoteSpec(cli),
             root,
             ...(values.watch ? { watch: true } : {}),
             ...(values.out ? { out: true } : {}),

package/dist/src/output.d.ts

@@ -1,4 +1,4 @@
-import type { IO } from "./render.js";
+import { type IO } from "./render.js";
 import type { Style } from "./style.js";
 export declare const EXIT_OK = 0;
 export declare const EXIT_ERROR = 1;
@@ -55,6 +55,24 @@ export declare class EngineErrorLike extends Error {
  * current-truth payload pretty-printed.
  */
 export declare function renderError(err: unknown, io: IO, style: Style, json: boolean): number;
+export interface HitLike {
+    id: string;
+    path: string;
+    [k: string]: unknown;
+}
+export declare const HIT_CELL_MAX = 60;
+/** Clip `s` to `max` visible characters, marking the cut with `…`. */
+export declare function truncateCell(s: string, max?: number): string;
+/** Render one projected value as a table cell (unstyled). */
+export declare function hitCell(v: unknown): string;
+/** The projected column names across `hits`: every key but the injected id/path,
+ *  in first-seen order. Empty when nothing was projected. */
+export declare function hitColumns(hits: HitLike[]): string[];
+/** Human-tier hit list: `<id>  <path>` lines, or an aligned table when projected. */
+export declare function renderHits(cli: {
+    io: IO;
+    style: Style;
+}, hits: HitLike[]): void;
 /** Loud truncation footer to stderr (§4.4). Exit code stays 0. */
 export declare function truncationFooter(io: IO, style: Style, cursor: number | string): void;
 export {};

package/dist/src/output.js

@@ -1,3 +1,4 @@
+import { columns, visibleWidth } from "./render.js";
 // Output contract + error rendering (11 §2.4, §4).
 //
 // Exit codes:  0 success (incl. truncated)  ·  1 typed engine error / conflict
@@ -124,6 +125,65 @@ function indent(s, pad) {
         .map((l) => pad + l)
         .join("\n");
 }
+export const HIT_CELL_MAX = 60;
+/** Clip `s` to `max` visible characters, marking the cut with `…`. */
+export function truncateCell(s, max = HIT_CELL_MAX) {
+    if (visibleWidth(s) <= max)
+        return s;
+    return [...s].slice(0, Math.max(max - 1, 0)).join("") + "…";
+}
+/** Render one projected value as a table cell (unstyled). */
+export function hitCell(v) {
+    if (v === null || v === undefined)
+        return "";
+    if (typeof v === "string") {
+        const nl = v.indexOf("\n");
+        return truncateCell(nl === -1 ? v : `${v.slice(0, nl)}…`);
+    }
+    if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint")
+        return String(v);
+    return truncateCell(JSON.stringify(v) ?? String(v));
+}
+/** The projected column names across `hits`: every key but the injected id/path,
+ *  in first-seen order. Empty when nothing was projected. */
+export function hitColumns(hits) {
+    const cols = [];
+    const seen = new Set(["id", "path"]);
+    for (const h of hits) {
+        for (const k of Object.keys(h)) {
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            cols.push(k);
+        }
+    }
+    return cols;
+}
+/** Human-tier hit list: `<id>  <path>` lines, or an aligned table when projected. */
+export function renderHits(cli, hits) {
+    const { io, style } = cli;
+    const projected = hitColumns(hits);
+    if (projected.length === 0) {
+        for (const h of hits)
+            io.out(`${style.id(h.id)}  ${style.accent(h.path)}`.trimEnd());
+        return;
+    }
+    const cols = projected.includes("$path") ? ["id", ...projected] : ["id", "path", ...projected];
+    const rows = [cols.map((c) => style.dim(c))];
+    for (const h of hits) {
+        rows.push(cols.map((c) => {
+            if (c === "id")
+                return style.id(h.id);
+            if (c === "path")
+                return style.accent(h.path);
+            if (c === "$path" && typeof h[c] === "string")
+                return style.accent(h[c]);
+            return hitCell(h[c]);
+        }));
+    }
+    for (const line of columns(rows))
+        io.out(line);
+}
 /** Loud truncation footer to stderr (§4.4). Exit code stays 0. */
 export function truncationFooter(io, style, cursor) {
     io.err(style.dim(`… truncated; continue with --cursor ${cursor}`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omgbase",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Open Markdown Graph Base — CLI",
   "license": "MIT",
   "repository": {
@@ -45,13 +45,13 @@
     "omg": "./dist/src/main.js"
   },
   "dependencies": {
-    "@omgbase/core": "^0.1.0",
+    "@omgbase/core": "^0.2.0",
     "@omgbase/fs-adapter": "^0.1.0",
-    "@omgbase/sync": "^0.1.0",
+    "@omgbase/sync": "^0.2.0",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@simplebrains/recital": "^0.8.0"
+    "@simplebrains/recital": "^0.8.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",