faf-cli 8.1.0 → 8.1.1

package/dist/interop/cards.d.ts

@@ -32,7 +32,8 @@ export interface AiCatalog {
     [key: string]: unknown;
 }
 export interface ProjectedCards {
-    block: Record<string, unknown>;
+    /** faf's context block — only when a project.faf was given (BEST). */
+    block?: Record<string, unknown>;
     a2a?: ProjectedA2A;
     mcp?: Record<string, unknown>;
     registry?: {
@@ -50,9 +51,11 @@ export interface ProjectedCards {
 export declare function readFafa(path: string): FafaDoc;
 /** Discover agent.fafa / .fafa (cwd, then one parent). */
 export declare function findFafaFile(dir?: string): string | null;
-/** Build the A2A Agent Card (JSON) from a .fafa + .faf: the core card
- *  ({@link projectA2ACard}) carrying FAF's context extension. */
-export declare function buildA2ACard(fafa: FafaDoc, faf: FafData, opts?: ProjectCardsOptions): ProjectedA2A;
+/** Build the A2A Agent Card (JSON) from a .fafa: the core card
+ *  ({@link projectA2ACard}). With a project.faf (BEST) it carries FAF's
+ *  context extension; with none (BETTER) it is the plain A2A card — the
+ *  .fafa is its source, and nothing on it points at a project.faf. */
+export declare function buildA2ACard(fafa: FafaDoc, faf?: FafData, opts?: ProjectCardsOptions): ProjectedA2A;
 /** @deprecated Use {@link buildA2ACard}. Removed in the next major. */
 export declare const generateA2ACard: typeof buildA2ACard;
 /**
@@ -66,7 +69,7 @@ export declare const generateA2ACard: typeof buildA2ACard;
  * an identifier is a catalog's primary key, and `urn:air:local:…` published to
  * the world is worse than a refusal a line of YAML fixes.
  */
-export declare function catalogEntriesFor(fafa: FafaDoc, faf: FafData, opts?: ProjectCardsOptions): CatalogEntry[];
+export declare function catalogEntriesFor(fafa: FafaDoc, faf?: FafData, opts?: ProjectCardsOptions): CatalogEntry[];
 /** Upsert projector entries into an existing catalog. Leaves every other row
  *  alone: a row is faf's only when its identifier is exactly faf's (never by
  *  type or URL). On match, only url / type / updatedAt move — host copy
@@ -90,8 +93,22 @@ export declare function upsertCatalogText(text: string | null, incoming: Catalog
     text: string;
     changed: boolean;
 };
+/** The cards an agent.fafa gives with no project.faf (BETTER): the A2A card
+ *  (when the .fafa names an A2A door), the AI Catalog and ARD. */
+export declare function betterTargets(fafa: FafaDoc, opts?: ProjectCardsOptions): CardTarget[];
+/** The cards that come from project.faf (BEST): the MCP Server Card and the
+ *  registry server.json. */
+export declare const BEST_ONLY: CardTarget[];
+/**
+ * Project the cards. The ladder: an agent.fafa alone gives BETTER — the plain
+ * A2A card, AI Catalog, ARD ({@link betterTargets}). A project.faf, resident
+ * and used, gives BEST — the same cards plus FAF's context extension on the
+ * A2A card, the MCP Server Card and the registry server.json. With no `faf`,
+ * a BEST target throws rather than point at a project.faf that is not there.
+ */
 export declare function projectCards(input: {
-    faf: FafData;
+    /** project.faf — absent means BETTER. */
+    faf?: FafData;
     fafa?: FafaDoc;
     targets?: CardTarget[];
     opts?: ProjectCardsOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faf-cli",
-  "version": "8.1.0",
+  "version": "8.1.1",
   "description": "Persistent AI context + memory — .faf and .fafm, IANA-registered. Anthropic-merged.",
   "type": "module",
   "icon": "https://faf.one/orange-smiley.svg",

package/project.faf

@@ -1,8 +1,8 @@
 faf_version: "3.0"
 project:
   name: faf-cli
-  version: "8.1.0"
-  goal: "CLI for IANA-registered `.faf` + `.fafm` — context DNA and portable agent memory. TypeScript, Bun-native since v6. package faf-cli v8.1.0 The Always33+ Edition — scored by the always-33 engine."
+  version: "8.1.1"
+  goal: "CLI for IANA-registered `.faf` + `.fafm` — context DNA and portable agent memory. TypeScript, Bun-native since v6. package faf-cli v8.1.1 The Always33+ Edition — scored by the always-33 engine."
   main_language: TypeScript
   type: cli  # found: package.json bin
 # Commands + key_files feed `faf export --agents` (hand values win over detection).
@@ -61,7 +61,7 @@ human_context:
   what: Persistent AI Context Standard — project DNA for AI. IANA-registered. Anthropic-merged.
   why: Eliminates 91% context re-discovery tax — define once, AI remembers forever
   where: npm registry, Homebrew, GitHub
-  when: Production since September 2025; Bun-native since v6; current package 8.1.0 (always-33 engine)
+  when: Production since September 2025; Bun-native since v6; current package 8.1.1 (always-33 engine)
   how: bunx faf-cli auto, then project.faf versions with your code — faf show renders it human-visible
 monorepo:
   packages_count: slotignored