@lanes-sh/link 0.6.11 → 0.7.0

package/src/cli/commands/owner/entities.ts

@@ -0,0 +1,244 @@
+import { ConfigError } from '#profile';
+import { scopeNamespace } from '#dispatch';
+import { scopeBlobStore, type BlobStore } from '#stores/blobs';
+import {
+  indexState,
+  openCatalogue,
+  rebuildCatalogue,
+  writeCatalogue,
+} from '#providers/entities/catalogue.ts';
+import { forgetEntity, persistEntity } from '#providers/entities/writes.ts';
+import { matchEntities, type Criteria } from '#providers/entities/find.ts';
+import { describe, renderEntity } from '#providers/entities/render.ts';
+import { entityStorage, type Attribute, type Entity, type Relation } from '#providers/owner.ts';
+import { heading, ok, print, style, table, warn } from '../../output.ts';
+import type { Runtime } from '../../runtime.ts';
+import { agreed, optionalStdin, ownerConnection, required, withRuntime, type OwnerFlags } from './shared.ts';
+
+/**
+ * `lanes link entities` — who and what everyone else is.
+ *
+ * Reaches the same bytes the provider does, through the same two scoping
+ * functions and the same `entityStorage`, `catalogue` and `find` modules. Two
+ * spellings of one layout is how a control plane and its data plane drift
+ * apart, and here it would drift in a way nothing would notice: a CLI that
+ * wrote entity files without maintaining `_index.json` would leave every write
+ * costing the next reader a full rebuild.
+ */
+
+/** `--attr email=jan@example.test`, or `--attr github` for "has one at all". */
+function parseAttr(given: string): { kind: string; value?: string } {
+  const at = given.indexOf('=');
+  if (at === -1) return { kind: given.trim() };
+  return { kind: given.slice(0, at).trim(), value: given.slice(at + 1).trim() };
+}
+
+/** `--related works_at=acme-bv`, or `--related acme-bv` for any predicate. */
+function parseRelated(given: string): { predicate?: string; entity: string } {
+  const at = given.indexOf('=');
+  if (at === -1) return { entity: given.trim() };
+  return { predicate: given.slice(0, at).trim(), entity: given.slice(at + 1).trim() };
+}
+
+function criteriaFrom(query: string | undefined, flags: OwnerFlags): Criteria {
+  return {
+    query,
+    type: flags.type,
+    tag: flags.tag,
+    attr: flags.attr?.map(parseAttr),
+    related: flags.related?.map(parseRelated),
+    limit: 50,
+  };
+}
+
+export async function entitiesFind(query: string | undefined, flags: OwnerFlags): Promise<void> {
+  await withRuntime(flags, async (runtime) => {
+    const store = entitiesStore(runtime, flags);
+    const catalogue = await openCatalogue(store);
+    const criteria = criteriaFrom(query, flags);
+    const matches = matchEntities(catalogue, criteria);
+
+    if (matches.candidates.length === 0) {
+      heading('Entities (0)');
+      print(
+        style.dim(
+          catalogue.entities.length === 0
+            ? '  none — declare one with: lanes link entities write <name>'
+            : `  nothing matches ${describe(criteria)}`,
+        ),
+      );
+      return;
+    }
+
+    heading(`Entities (${matches.total})`);
+    table(
+      matches.candidates.map((candidate) => [
+        `  ${candidate.entity.id}`,
+        candidate.entity.name,
+        candidate.entity.type ? style.dim(candidate.entity.type) : '',
+        style.dim(candidate.entity.updatedAt.slice(0, 10)),
+      ]),
+    );
+
+    // The same sentence the tool result carries, for the same reason: the list
+    // is not a ranking, and the person reading it is about to pick from it.
+    if (matches.candidates.length > 1 && query !== undefined) {
+      print('');
+      print(style.dim('  more than one matches — the order is not a ranking'));
+    }
+  });
+}
+
+export async function entitiesGet(id: string | undefined, flags: OwnerFlags): Promise<void> {
+  const entityId = required(id, 'lanes link entities get <id>');
+
+  await withRuntime(flags, async (runtime) => {
+    const store = entitiesStore(runtime, flags);
+    const entity = await entityStorage.read(store, entityId);
+    if (!entity) throw new ConfigError(`No entity "${entityId}" in this profile.`);
+
+    const catalogue = await openCatalogue(store);
+    print('');
+    print(renderEntity(entity, catalogue, entity.body));
+  });
+}
+
+export async function entitiesWrite(name: string | undefined, flags: OwnerFlags): Promise<void> {
+  const given = required(name, 'lanes link entities write <name> [--type person] [--attr email=…]');
+  // Optional rather than required: an entity legitimately has no prose, and
+  // refusing an empty pipe would break every scripted invocation.
+  const notes = await optionalStdin();
+
+  await withRuntime(flags, async (runtime) => {
+    const store = entitiesStore(runtime, flags);
+    const id = flags.name ?? entityStorage.slugify(given);
+    const existing = await entityStorage.read(store, id);
+
+    const attributes = flags.attr?.map((one) => {
+      const { kind, value } = parseAttr(one);
+      if (value === undefined) {
+        throw new ConfigError(`--attr ${one} needs a value here: --attr ${kind}=<value>`);
+      }
+      return { kind, value } satisfies Attribute;
+    });
+
+    const relations = flags.related?.map((one) => {
+      const { predicate, entity } = parseRelated(one);
+      if (predicate === undefined) {
+        throw new ConfigError(`--related ${one} needs a predicate: --related <predicate>=${entity}`);
+      }
+      return { predicate, entity } satisfies Relation;
+    });
+
+    // A flag that was not passed keeps what is on disk, exactly as the tool
+    // does — `entities write` is how a person corrects one field.
+    const next: Entity = {
+      id,
+      name: given,
+      type: flags.type ?? existing?.type ?? '',
+      aliases: flags.alias ?? existing?.aliases ?? [],
+      tags: flags.tag ? [flags.tag] : (existing?.tags ?? []),
+      attributes: attributes ?? existing?.attributes ?? [],
+      relations: relations ?? existing?.relations ?? [],
+      updatedAt: new Date().toISOString(),
+      body: notes ?? existing?.body ?? '',
+      bytes: 0,
+    };
+
+    await persistEntity(store, next);
+    print(ok(`${existing ? 'updated' : 'declared'} entity ${style.bold(id)}`));
+  });
+}
+
+export async function entitiesLink(
+  from: string | undefined,
+  edge: string | undefined,
+  flags: OwnerFlags,
+): Promise<void> {
+  const usage = 'lanes link entities link <from> <predicate>=<to>';
+  const given = required(from, usage);
+  const { predicate, entity: to } = parseRelated(required(edge, usage));
+  if (predicate === undefined) {
+    throw new ConfigError(`"${edge}" needs a predicate — ${usage}`);
+  }
+
+  await withRuntime(flags, async (runtime) => {
+    const store = entitiesStore(runtime, flags);
+    const entity = await entityStorage.read(store, given);
+    if (!entity) throw new ConfigError(`No entity "${given}" in this profile.`);
+
+    if (entity.relations.some((one) => one.predicate === predicate && one.entity === to)) {
+      print(style.dim(`  ${given} already ${predicate} ${to}`));
+      return;
+    }
+
+    await persistEntity(store, {
+      ...entity,
+      relations: [...entity.relations, { predicate, entity: to }],
+      updatedAt: new Date().toISOString(),
+    });
+
+    const catalogue = await openCatalogue(store);
+    print(ok(`${style.bold(given)} ${predicate} ${style.bold(to)}`));
+    if (!catalogue.byId.has(to)) print(warn(`"${to}" is not declared yet — the edge is kept as written`));
+  });
+}
+
+export async function entitiesForget(id: string | undefined, flags: OwnerFlags): Promise<void> {
+  const entityId = required(id, 'lanes link entities forget <id>');
+
+  await withRuntime(flags, async (runtime) => {
+    const store = entitiesStore(runtime, flags);
+    const catalogue = await openCatalogue(store);
+    const entity = catalogue.byId.get(entityId);
+    if (!entity) throw new ConfigError(`No entity "${entityId}" in this profile.`);
+
+    const referencedBy = (catalogue.backlinks.get(entityId) ?? []).map((one) => one.from);
+
+    print(`  ${style.bold(entity.id)}  ${entity.name}`);
+    // Said before the prompt rather than after the delete: this is the fact
+    // that should change the answer, and `forget` deliberately does not cascade.
+    if (referencedBy.length > 0) {
+      print(warn(`still referenced by ${referencedBy.join(', ')} — those edges will dangle`));
+    }
+    if (!(await agreed(flags, 'Remove this entity?'))) return;
+
+    await forgetEntity(store, catalogue, entityId, new Date().toISOString());
+
+    print(ok(`removed entity ${style.bold(entityId)}`));
+  });
+}
+
+/**
+ * Rebuild `_index.json` from the files, and say why it needed it.
+ *
+ * The index self-heals on the next write, so this exists for the case a write
+ * is not coming: a bulk edit made in an editor or pulled from a knowledge
+ * repository, where the next read would otherwise pay a full scan every time.
+ */
+export async function entitiesReindex(flags: OwnerFlags): Promise<void> {
+  await withRuntime(flags, async (runtime) => {
+    const store = entitiesStore(runtime, flags);
+    const before = await indexState(store);
+
+    if (before.current) {
+      print(style.dim(`  index is already current — ${before.reason}`));
+      return;
+    }
+
+    const catalogue = await rebuildCatalogue(store);
+    await writeCatalogue(store, catalogue.entities, catalogue.fingerprint, new Date().toISOString());
+    print(ok(`rebuilt the index over ${catalogue.entities.length} entities — ${before.reason}`));
+  });
+}
+
+/**
+ * The blob namespace core would scope this provider to.
+ *
+ * The same two functions `buildProviderContext` uses, for the reason
+ * `memoryStore` gives: a path spelled out again is a path that can differ.
+ */
+export function entitiesStore(runtime: Runtime, flags: OwnerFlags): BlobStore {
+  const connection = ownerConnection(runtime.config, 'entities', flags);
+  return scopeBlobStore(runtime.storage, scopeNamespace('entities', connection));
+}

package/src/cli/commands/owner/shared.ts

@@ -26,6 +26,20 @@ export interface OwnerFlags extends GlobalFlags {
   readonly name?: string | undefined;
   /** `assets`: for the file whose extension does not say what it is. */
   readonly contentType?: string | undefined;
+  /** `entities`: person, company, project — free-form, never a closed list. */
+  readonly type?: string | undefined;
+  /**
+   * `entities`: repeatable, which is why `ownerFlags` needs argv.
+   *
+   * `parseArgv` keeps only the last value of a repeated flag, and an entity
+   * with two email addresses is the case this whole component exists for — so
+   * these three read the raw argv through `all()`, as `customFlags` does.
+   */
+  readonly alias?: readonly string[] | undefined;
+  /** `entities`: `email=jan@example.test`, or `github` to mean "has one". */
+  readonly attr?: readonly string[] | undefined;
+  /** `entities`: `works_at=acme-bv`, or `acme-bv` for any predicate. */
+  readonly related?: readonly string[] | undefined;
   /** Reveal a vault value on a terminal. */
   readonly show?: boolean | undefined;
   /** Print only the value, for `$(…)`. */

package/src/cli/commands/owner/vault.ts

@@ -15,7 +15,7 @@ import {
  *
  * `lanes link vault get` prints a value, which `lanes link secrets` deliberately never does.
  * That is the two-kinds-of-secret distinction doing its job
- * (`docs/detailed/security.md`): a credential authorises the system and is never
+ * (`https://lanes.sh/docs/link/security`): a credential authorises the system and is never
  * disclosed, and a vault the owner cannot read without an agent is not a vault.
  */
 
@@ -136,5 +136,5 @@ export function vaultKeyGenerate(flags: OwnerFlags): void {
   print('');
   print(style.dim('  Store it as LANES_LINK_VAULT_KEY. It is not written anywhere by this command:'));
   print(style.dim('  a key kept beside the document it protects protects nothing.'));
-  print(style.dim('  Separate from the credential-store key, deliberately — docs/detailed/security.md.'));
+  print(style.dim('  Separate from the credential-store key, deliberately — https://lanes.sh/docs/link/security.'));
 }

package/src/cli/commands/owner.ts

@@ -1,6 +1,6 @@
 /**
- * `lanes link memory`, `tasks`, `assets`, `skills`, `vault` — the owner layer's
- * control plane.
+ * `lanes link memory`, `tasks`, `assets`, `skills`, `vault`, `entities` — the
+ * owner layer's control plane.
  *
  * The layer shipped in M4 with no CLI at all, so the two stores holding the
  * owner's *own* data were reachable only by an agent, and the one thing that
@@ -22,7 +22,7 @@
  * MCP because ADR-014 §1 decided a policy-gated grant beats a missing path.
  *
  * One noun per file — `memory.ts`, `tasks.ts`, `assets.ts`, `skills.ts`,
- * `vault.ts` — over the shape they all share in `shared.ts`: the flag type, the
+ * `vault.ts`, `entities.ts` — over the shape they all share in `shared.ts`: the flag type, the
  * open-announce-act-close wrapper, connection resolution, and the two prompts.
  */
 
@@ -40,6 +40,16 @@ export { assetsAdd, assetsGet, assetsList, assetsRemove } from './owner/assets.t
 
 export { skillsAdd, skillsList, skillsRemove, skillsShow } from './owner/skills.ts';
 
+export {
+  entitiesFind,
+  entitiesForget,
+  entitiesGet,
+  entitiesLink,
+  entitiesReindex,
+  entitiesStore,
+  entitiesWrite,
+} from './owner/entities.ts';
+
 export {
   vaultGet,
   vaultKeyGenerate,

package/src/cli/commands/setup.ts

@@ -128,6 +128,18 @@ function renderOne(plan: ProviderPlan, missing: ReadonlySet<string>): void {
     }
   }
 
+  if (plan.variables.length > 0) {
+    // Its own heading rather than a row under "Values it needs", because there
+    // is nothing to store ahead of time: `connect` asks for these and writes
+    // them to the connection, so the useful thing to show is what will be asked
+    // and what an answer looks like.
+    heading('Where it is');
+    for (const variable of plan.variables) {
+      print(`  ${style.bold(variable.label)}  ${style.dim(`e.g. ${variable.example}`)}`);
+      print(`    ${style.dim(variable.description)}`);
+    }
+  }
+
   heading('Then');
   print(`  ${plan.command}`);
 

package/src/cli/config-edit.ts

@@ -282,7 +282,7 @@ oauth_apps: {}
 # reports — an address, a workspace — so this list says whose data is reachable
 # without having to look anything up.
 #
-# The six below hold no account, and that is why they are here already: they
+# The seven below hold no account, and that is why they are here already: they
 # reach your own material rather than anybody's API, so there was never anything
 # for a connect step to authorise (ADR-050). What each one is:
 #
@@ -292,6 +292,9 @@ oauth_apps: {}
 #   skills   procedures you have written, handed to an agent as instructions
 #   vault    passwords and API keys, released one at a time
 #   setup    what is connected here, and what connecting more would take
+#   entities the people, companies and projects you deal with, and how to
+#            reach each of them — so an agent looks an address up rather
+#            than recalling one
 #
 # Nothing is stored in any of them until you or an agent puts something there,
 # and none of them can read an account. To switch one off, deny it below —
@@ -304,6 +307,7 @@ connections:
   - { id: main, provider: skills, account: Skills }
   - { id: main, provider: vault, account: Vault }
   - { id: main, provider: setup, account: Setup }
+  - { id: main, provider: entities, account: Entities }
 
 # Only what is listed here is reachable, and an empty policy grants nothing.
 #
@@ -317,19 +321,25 @@ connections:
 #   allow: [notion.*, gmail.*]    two providers
 #   deny:  [gmail.send_message]   a deny always beats an allow
 #
-# The rules below grant each of the six its whole namespace, writes included —
+# The rules below grant each of the seven its whole namespace, writes included —
 # the same thing "connect memory" wrote when it was a command you had to run.
 # Narrowing is one line, and these are the three worth knowing:
 #
-#   deny: [memory.write]          memory becomes read-only
-#   deny: [skills.manage.*]       skills can be invoked but not authored
-#   deny: [vault.put, vault.remove]   nothing new can be stored
+#   deny: [memory.write, memory.forget]   memory becomes read-only
+#   deny: [skills.manage.*]               skills can be invoked but not authored
+#   deny: [vault.put, vault.remove]       nothing new can be stored
+#   deny: [entities.write, entities.link, entities.forget]
+#                                         entities becomes read-only
+#
+# Those lists are exhaustive on purpose: a namespace is read-only only when
+# every capability that changes something is named, so "deny: [memory.write]"
+# alone leaves "memory.forget" granted.
 #
 # A vault read is not granted by "vault.*" alone: each stored item is its own
 # "vault.get.<id>" capability and only appears after a restart, so a write can
 # never hand itself a read (ADR-012).
 policy:
-  allow: [memory.*, tasks.*, assets.*, skills.*, vault.*, setup.*]
+  allow: [memory.*, tasks.*, assets.*, skills.*, vault.*, setup.*, entities.*]
   deny: []
 `;
 }

package/src/cli/config-repair.ts

@@ -27,6 +27,7 @@ const RESERVED_SURFACES = {
   vault: 'Vault',
   setup: 'Setup',
   identity: 'Identity',
+  entities: 'Entities',
 } as const;
 
 type ReservedSurface = keyof typeof RESERVED_SURFACES;
@@ -42,6 +43,14 @@ type ReservedSurface = keyof typeof RESERVED_SURFACES;
  * which is ADR-050's whole argument — so a profile written before those existed
  * gets them on the next command rather than needing five of its own.
  *
+ * `entities` is on the list and `identity` is not, which reads as inconsistent
+ * until the test is stated exactly. It is not "is it empty" — memory arrives
+ * empty and is granted. It is **can it be filled in from here**: identity is
+ * configuration, changed in the CLI under ADR-007, so a surface that reported
+ * an empty one could never do anything about it. Entities accumulate on the
+ * same surface that reads them, so an empty one is a store waiting to be used
+ * rather than a tool with nothing to say (ADR-056).
+ *
  * Ordered as `RESERVED_PROVIDER_IDS` is, so a repair reports in the order the
  * template writes and a diff between the two reads as a diff.
  */
@@ -52,6 +61,7 @@ export const DEFAULT_SURFACES: readonly ReservedSurface[] = [
   'skills',
   'vault',
   'setup',
+  'entities',
 ];
 
 /**

package/src/cli/dispatch-owner.ts

@@ -3,6 +3,12 @@ import {
   assetsGet,
   assetsList,
   assetsRemove,
+  entitiesFind,
+  entitiesForget,
+  entitiesGet,
+  entitiesLink,
+  entitiesReindex,
+  entitiesWrite,
   memoryForget,
   memoryGet,
   memoryList,
@@ -25,7 +31,8 @@ import {
 } from './commands/owner.ts';
 
 /**
- * The commands over the owner's own data: memory, tasks, assets, skills, vault.
+ * The commands over the owner's own data: memory, tasks, assets, skills, vault,
+ * entities.
  *
  * Split out of `main.ts` for the reason the budget in `src/architecture.test.ts`
  * exists to find, rather than to satisfy a line count. These are one subject —
@@ -125,6 +132,28 @@ export function dispatchOwner(
           throw new Error(`Unknown: ${program} vault ${second}`);
       }
 
+    case 'entities':
+      switch (second) {
+        // Bare `entities` is a listing, which is `find` with no criteria — one
+        // name for one concept rather than a `list` that would be the same code
+        // under a second word.
+        case 'find':
+        case undefined:
+          return entitiesFind(rest[0], owner);
+        case 'get':
+          return entitiesGet(rest[0], owner);
+        case 'write':
+          return entitiesWrite(rest[0], owner);
+        case 'link':
+          return entitiesLink(rest[0], rest[1], owner);
+        case 'forget':
+          return entitiesForget(rest[0], owner);
+        case 'reindex':
+          return entitiesReindex(owner);
+        default:
+          throw new Error(`Unknown: ${program} entities ${second}`);
+      }
+
     default:
       // Unreachable: `main.ts` narrows to the nouns above before calling. Kept
       // so that adding one there and forgetting it here is a thrown error rather

package/src/cli/main.ts

@@ -58,7 +58,7 @@ export async function run(argv: readonly string[]): Promise<void> {
   const [first, second, ...rest] = command;
 
   const global = globalFlags(flags);
-  const owner = ownerFlags(flags);
+  const owner = ownerFlags(flags, argv);
 
   const show = flags['show'] === true;
   const raw = flags['raw'] === true;
@@ -260,6 +260,7 @@ export async function run(argv: readonly string[]): Promise<void> {
     case 'assets':
     case 'skills':
     case 'vault':
+    case 'entities':
       return dispatchOwner(first, second, rest, owner, PROGRAM);
 
     // Beside `memory` and `skills` because it is the question they raise next:

package/src/cli/runtime/open.ts

@@ -6,7 +6,6 @@ import type { BlobStore } from '#stores/blobs';
 import type { AnyConnector, ProviderManifest } from '#connectivity';
 import { RateLimiter, allowedConnections } from '#policy';
 import {
-  KNOWLEDGE_LAYOUT,
   layout,
   listProfiles,
   workspacePath,
@@ -26,7 +25,7 @@ import {
   type StorageFactory,
   type TargetInput,
 } from '#deployments/target.ts';
-import { openKnowledge, type FetchLike, type KnowledgeStores } from '#deployments/knowledge.ts';
+import { knowledgeRoutes, openKnowledge, type FetchLike, type KnowledgeStores } from '#deployments/knowledge.ts';
 import { routeBlobStore } from '#stores/blobs/route.ts';
 import { connectorFactory } from '#connectivity/transports';
 import { requestAuthorizer } from '#connectivity/auth/index.ts';
@@ -174,9 +173,7 @@ export async function openRuntime(
   // The audit log, `state.kv`, the credential store and the vault keep their
   // own roots on the target's own storage and are untouched.
   const knowledge = await openKnowledge(adapters, credentials, options.fetch);
-  const storage = knowledge
-    ? routeBlobStore(storageFor(), [{ prefix: `${KNOWLEDGE_LAYOUT.memory}/`, store: knowledge.memory }])
-    : storageFor();
+  const storage = knowledge ? routeBlobStore(storageFor(), knowledgeRoutes(knowledge)) : storageFor();
   const state = openState(storageFor, config.instance.profile);
 
   // The durable log, plus any copies the target declares. `sink` is what
@@ -195,7 +192,7 @@ export async function openRuntime(
   // The vault's own store, beside the credential store and never it: a separate
   // document, a separate key, and a separate environment variable
   // (`LANES_LINK_VAULT_KEY`). One master secret reused across purposes turns any
-  // single compromise into a total one — `docs/detailed/security.md`, and the boundary
+  // single compromise into a total one — `https://lanes.sh/docs/link/security`, and the boundary
   // test that has existed since M1.
   //
   // Opened before the registry because each stored item becomes its own
@@ -327,7 +324,14 @@ export async function openRuntime(
   // dispatcher and the CLI share it deliberately: a stateful connector must be
   // the *same instance* whichever side asks for it, or a held session is held
   // twice.
-  const connectorFor = connectorFactory({ registry, credentials });
+  const connectorFor = connectorFactory({
+    registry,
+    credentials,
+    // From the connection row, which is where a per-connection setting has
+    // always lived. One lookup behind both, so they cannot disagree.
+    connectionConfig: (provider, id) => row(config, provider, id)?.config,
+    isDeclared: (provider, id) => row(config, provider, id) !== undefined,
+  });
   const authorizeRequest = requestAuthorizer(registry, credentials);
   let closed = false;
 
@@ -385,3 +389,6 @@ export async function openRuntime(
     },
   };
 }
+
+const row = (config: Config, provider: string, id: string) =>
+  config.connections.find((connection) => connection.provider === provider && connection.id === id);

package/src/cli/runtime/registry.ts

@@ -13,6 +13,7 @@ import {
   createSetupProvider,
   createSkillsProvider,
   createVaultProvider,
+  entitiesProvider,
   memoryProvider,
   tasksProvider,
   type IdentityProviderOptions,
@@ -87,7 +88,7 @@ export interface OwnerLayerOptions {
  * from, which is what lets workspace YAML register alongside these.
  *
  * `allowReserved` is what admits `memory`, `tasks`, `assets`, `skills`, `vault`,
- * `setup`, and `identity`. The guard
+ * `setup`, `identity` and `entities`. The guard
  * stays rather than being retired: it exists so a *third-party* provider cannot
  * claim a namespace whose policy rules would then silently mean something else,
  * and that reason survives the owner layer shipping. Only this one construction
@@ -104,6 +105,10 @@ export function buildRegistry(owner: OwnerLayerOptions = {}): ProviderRegistry {
   registry.register(memoryProvider);
   registry.register(tasksProvider);
   registry.register(assetsProvider);
+  // `entities` is a fourth of the same shape: what it holds is the owner's, and
+  // its derived index lives in the same scoped store, so there is nothing to
+  // hand in here either.
+  registry.register(entitiesProvider);
   registry.register(skillsProviderFor(owner));
   registry.register(
     createVaultProvider({

package/src/cli/selection.ts

@@ -168,6 +168,7 @@ export const SELECTION: Record<string, Requires> = {
   assets: 'profile+target',
   skills: 'profile+target',
   vault: 'profile+target',
+  entities: 'profile+target',
   // Both halves open the target's adapters — `show` counts what is in the
   // stores, and `use` migrates between them — and both edit the profile's
   // config. Neither can be answered without being told which.
@@ -198,6 +199,9 @@ const SUBCOMMANDS: Record<string, readonly string[]> = {
   assets: ['list', 'get', 'add', 'remove'],
   skills: ['list', 'show', 'add', 'remove'],
   vault: ['list', 'get', 'set', 'remove', 'key'],
+  // No `list`: a bare `entities` is a listing, which is `find` with no
+  // criteria. One concept, one word.
+  entities: ['find', 'get', 'write', 'link', 'forget', 'reindex'],
   mcp: ['skill', 'add', 'stdio', 'list'],
   secrets: ['push', 'set', 'list'],
   knowledge: ['show', 'use'],
@@ -253,6 +257,9 @@ const ACCEPTS: Record<string, readonly string[]> = {
   connect: [
     'id',
     'display-name',
+    // Repeatable: `--set host=cloud.example.com`. The only way to give a
+    // provider its address without a terminal to ask at.
+    'set',
     'label',
     'replace',
     'non-interactive',
@@ -306,6 +313,10 @@ const ACCEPTS: Record<string, readonly string[]> = {
   assets: ['connection', 'name', 'content-type', 'yes'],
   skills: ['connection', 'title', 'description', 'file'],
   vault: ['connection'],
+  // `alias`, `attr` and `related` are repeatable — see `ownerFlags`. `name`
+  // overrides the id derived from the positional name, which is how you get
+  // `acme-bv` rather than `acme-b-v`.
+  entities: ['connection', 'type', 'name', 'alias', 'attr', 'related', 'tag', 'yes'],
   // `no-migrate` is listed beside `migrate` because they are three states
   // rather than two: neither one asks, and a run with no terminal has to be
   // able to say which it meant (ADR-041).

package/src/cli/usage.ts

@@ -100,6 +100,17 @@ ${style.bold('Your own context')}
   ${PROGRAM} skills add <name> [--file f]             document on stdin
   ${PROGRAM} skills remove <name>
 
+  ${PROGRAM} entities                 who and what everyone else is
+  ${PROGRAM} entities find [query] [--type t] [--tag t] [--attr kind[=value]]
+                                 [--related predicate=id]   every match, never a choice
+  ${PROGRAM} entities get <id>                   with its relationships, both ways
+  ${PROGRAM} entities write <name> [--type t] [--name id] [--alias a]
+                                 [--attr kind=value] [--related predicate=id]
+                                 notes on stdin; a flag you omit keeps what is stored
+  ${PROGRAM} entities link <from> <predicate>=<to>       one edge, written on <from> only
+  ${PROGRAM} entities forget <id>
+  ${PROGRAM} entities reindex                    rebuild the lookup index from the files
+
   ${PROGRAM} knowledge show            where memory and skills are kept, and how many
   ${PROGRAM} knowledge use github --repo <owner/name> [--branch b] [--path p]
                                  keep both in a private repository, over the GitHub API
@@ -152,8 +163,8 @@ ${style.bold('Naming what a command acts on')}
                                  command that names neither refuses and lists what exists.
 
 ${style.bold('Other flags')}
-  --connection <id>              which memory/tasks/assets/skills/vault connection, where
-                                 a profile has several of one kind
+  --connection <id>              which memory/tasks/assets/skills/vault/entities
+                                 connection, where a profile has several of one kind
   --yes                          skip the confirmation a destructive command would ask for
   --json                         machine-readable output, where a command offers it
   --non-interactive              never prompt: connect refuses with what to store,

package/src/connectivity/auth/strategy/index.ts

@@ -133,6 +133,6 @@ export function strategyContextFrom(input: {
 export function refuseStrategy(strategy: string): never {
   throw new Error(
     `Auth strategy "${strategy}" is not registered. ` +
-      `Strategies are the only place per-vendor code belongs; see docs/detailed/creating-a-provider.md.`,
+      `Strategies are the only place per-vendor code belongs; see https://lanes.sh/docs/link/creating-a-provider.`,
   );
 }

package/src/connectivity/capability.ts

@@ -8,7 +8,7 @@ import type { ProviderContext } from './context.ts';
  * Do not make everything a tool. Use resources for read-oriented document or
  * structured context, tools for actions and parameterised queries, prompts for
  * reusable procedures. Decide per capability and record the reasoning in
- * `docs/detailed/providers.md` — ADR-006.
+ * `https://lanes.sh/docs/link/capabilities` — ADR-006.
  */
 export type Capability = ToolCapability | ResourceCapability | PromptCapability;