@remnic/core 9.3.689 → 9.3.691

package/dist/topics.d.ts

@@ -1,4 +1,4 @@
-import { g as MemoryFile, T as TopicScore } from './types-Dm5xxVrr.js';
+import { g as MemoryFile, T as TopicScore } from './types-2NoBoRBM.js';
 import './types-ByK7T3L6.js';
 import './index-DJ9QWMw-.js';
 

package/dist/transcript.d.ts

@@ -1,4 +1,4 @@
-import { P as PluginConfig, _ as TranscriptEntry, $ as Checkpoint } from './types-Dm5xxVrr.js';
+import { P as PluginConfig, _ as TranscriptEntry, $ as Checkpoint } from './types-2NoBoRBM.js';
 import { SessionIntegrityReport } from './session-integrity.js';
 import './types-ByK7T3L6.js';
 import './index-DJ9QWMw-.js';

package/dist/transfer/autodetect.js

@@ -4,8 +4,8 @@ import {
 import "../chunk-2DL3OFLD.js";
 import "../chunk-G4IAEX6D.js";
 import "../chunk-765K3SAT.js";
-import "../chunk-WEHSQBFR.js";
 import "../chunk-J4EB7DNW.js";
+import "../chunk-WEHSQBFR.js";
 import "../chunk-UI3NYK34.js";
 import "../chunk-GCGJW34D.js";
 import "../chunk-PZ5AY32C.js";

package/dist/transfer/backup.js

@@ -2,8 +2,8 @@ import {
   backupMemoryDir
 } from "../chunk-2NLLXCJG.js";
 import "../chunk-765K3SAT.js";
-import "../chunk-X7Y7WX73.js";
 import "../chunk-J4EB7DNW.js";
+import "../chunk-X7Y7WX73.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";
 import "../chunk-FP2373TW.js";

package/dist/transfer/capsule-export.js

@@ -1,10 +1,10 @@
 import {
   exportCapsule,
   isValidCapsuleSince
-} from "../chunk-KQAFEZQX.js";
+} from "../chunk-IPLYGWQF.js";
+import "../chunk-J4EB7DNW.js";
 import "../chunk-WEHSQBFR.js";
 import "../chunk-X7Y7WX73.js";
-import "../chunk-J4EB7DNW.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";
 import "../chunk-FP2373TW.js";

package/dist/{types-Dm5xxVrr.d.ts → types-2NoBoRBM.d.ts}

@@ -1062,6 +1062,25 @@ interface PluginConfig {
      * filtered out.
      */
     temporalSupersessionIncludeInRecall: boolean;
+    /**
+     * Bi-temporal validity master gate (issue #1578). When `false` (default),
+     * the recall validity-injection filter and `asOf` semantics behave
+     * byte-identically to pre-#1578.
+     *
+     * Turn on to exclude validity-expired facts from default injection
+     * candidates (they remain findable by explicit search and `as_of`
+     * queries). Storage round-trips `observedAt`/`eventTimeSource`; the
+     * extraction prompt → `resolveEventTime` write-time wiring lands in a
+     * follow-on PR, so new extractions are not yet event-time-resolved.
+     */
+    temporalBiTemporal: boolean;
+    /**
+     * Escape hatch for the bi-temporal injection filter (issue #1578). When
+     * `true`, facts whose `[valid_at, invalid_at)` interval ended before now
+     * are kept in injection candidates even with `temporalBiTemporal` on — some
+     * deployments prefer the older (always-inject) behavior. Default `false`.
+     */
+    temporalExpiredInInjection: boolean;
     /**
      * When true, recall checks whether a single validated memory in a
      * high-trust taxonomy bucket can answer the query before invoking QMD.
@@ -2570,6 +2589,25 @@ interface MemoryFrontmatter {
      * point in time.
      */
     invalid_at?: string;
+    /**
+     * Ingestion time (issue #1578) — when Remnic *learned* this fact.
+     * Distinct from `created` (file creation) and `valid_at` (event-time
+     * start).  Aligns with the source turn timestamp (#1575
+     * `sources[].observedAt`).  When `eventTimeSource === "assumed"`,
+     * `valid_at` is copied from this value.
+     */
+    observedAt?: string;
+    /**
+     * Provenance of the event-time interval (issue #1578).
+     *   - `"extracted"` — a per-fact `eventTime` expression was resolved
+     *     against the source turn's timestamp and produced `valid_at` /
+     *     `invalid_at`.
+     *   - `"assumed"` — no resolvable expression; `valid_at` was copied from
+     *     `observedAt` (the ingestion anchor).
+     * Absent on memories written before #1578; readers treat absent as
+     * `"assumed"` for display purposes.
+     */
+    eventTimeSource?: "extracted" | "assumed";
     /**
      * Timestamp when the operator explicitly forgot this memory
      * (issue #686 PR 4/6).  Set by `remnic forget <id>`.  Memories with

package/dist/types.d.ts

@@ -1,3 +1,3 @@
 import './types-ByK7T3L6.js';
 import './index-DJ9QWMw-.js';
-export { y as AccessTrackingEntry, A as ActiveRecallChatType, d as ActiveRecallModelFallbackPolicy, b as ActiveRecallPromptStyle, a as ActiveRecallQueryMode, c as ActiveRecallThinking, a7 as AgentAccessAuthToken, b6 as AgentAccessHttpConfig, b7 as AgentDefaultsConfig, b8 as AgentPersona, f as AgentPersonaModelConfig, b9 as BehaviorLoopAdjustment, e as BehaviorLoopPolicyState, ba as BehaviorSignalDirection, B as BehaviorSignalEvent, bb as BehaviorSignalType, aL as BootstrapOptions, aM as BootstrapResult, W as BriefingActiveThread, bc as BriefingCalendarSourceError, aS as BriefingConfig, S as BriefingFocus, O as BriefingFollowup, aT as BriefingOpenCommitment, Y as BriefingRecentEntity, X as BriefingResult, N as BriefingSections, aU as BriefingWindow, bd as BufferEntryState, k as BufferState, o as BufferSurpriseEvent, Z as BufferTurn, V as CalendarEvent, U as CalendarSource, be as CaptureMode, $ as Checkpoint, bf as CodexCliReasoningEffort, bg as CodexCompactionFlushMode, aV as CodexCompatConfig, bh as CodexConnectorConfig, aK as CodingContext, bi as CodingKnowledgeConfig, aP as CodingModeConfig, bj as CompressionGuidelineActivationState, a9 as CompressionGuidelineOptimizerActionSummary, a8 as CompressionGuidelineOptimizerEventCounts, aa as CompressionGuidelineOptimizerRuleUpdate, bk as CompressionGuidelineOptimizerSourceWindow, C as CompressionGuidelineOptimizerState, bl as ConfidenceTier, bm as ConsolidationAction, bn as ConsolidationItem, aN as ConsolidationObservation, ag as ConsolidationResult, s as ContinuityImprovementLoop, r as ContinuityIncidentCloseInput, p as ContinuityIncidentOpenInput, q as ContinuityIncidentRecord, bo as ContinuityIncidentState, bp as ContinuityLoopCadence, u as ContinuityLoopReviewInput, bq as ContinuityLoopStatus, t as ContinuityLoopUpsertInput, br as ContradictionScanConfig, au as ConversationThread, bs as CronConversationRecallMode, bt as CronRecallMode, aW as DEFAULT_RECALL_DISCLOSURE, ah as DaySummaryResult, bu as DreamingConfig, bv as DreamingNarrativePromptStyle, bw as DreamsDeepSleepConfig, bx as DreamsLightSleepConfig, ay as DreamsPhase, by as DreamsPhaseStatus, bz as DreamsPhasesConfig, bA as DreamsRemConfig, az as DreamsRunResult, ax as DreamsStatusResult, bB as EngramTraceEvent, w as EntityActivityEntry, x as EntityFile, ac as EntityMention, v as EntityRelationship, ad as EntitySchemaDefinition, ae as EntitySchemaSectionDefinition, E as EntityStructuredSection, aO as EntityTimelineEntry, aX as ExtractedFact, bC as ExtractedProcedureStep, bD as ExtractedQuestion, bE as ExtractedReasoningTrace, bF as ExtractedReasoningTraceStep, bG as ExtractedRelationship, bH as ExtractionPassSource, af as ExtractionResult, F as FileHygieneConfig, G as GatewayConfig, bI as GitHubLiveConnectorConfig, bJ as GmailLiveConnectorConfig, bK as GoogleDriveLiveConnectorConfig, bL as HeartbeatConfig, bM as HeartbeatDetectionMode, a0 as HourlySummary, J as IdentityInjectionMode, a5 as ImportanceLevel, I as ImportanceScore, a2 as LifecycleState, L as LiveConnectorsConfig, bN as LlmTraceCallback, bO as LlmTraceEvent, ak as MemoryActionEligibilityContext, aY as MemoryActionEligibilitySource, m as MemoryActionEvent, bP as MemoryActionOutcome, bQ as MemoryActionPolicyDecision, al as MemoryActionPolicyResult, bR as MemoryActionStatus, ab as MemoryActionType, M as MemoryCategory, g as MemoryFile, j as MemoryFrontmatter, ai as MemoryIntent, n as MemoryLifecycleEvent, am as MemoryLifecycleEventType, an as MemoryLifecycleStateSummary, i as MemoryLink, bS as MemoryLinkType, aZ as MemoryObservation, bT as MemoryOsPresetName, z as MemoryProjectionCurrentState, a_ as MemoryScope, h as MemoryStatus, D as MemorySummary, l as MetaState, bU as ModelApi, bV as ModelDefinitionConfig, bW as ModelProviderAuthMode, ao as ModelProviderConfig, bX as NamespacePolicy, ap as NativeKnowledgeConfig, bY as NativeKnowledgeFolderRuleConfig, bZ as NativeKnowledgeObsidianVaultConfig, b_ as NativeKnowledgeOpenClawWorkspaceConfig, b$ as NotionLiveConnectorConfig, P as PluginConfig, a4 as PolicyClass, c0 as PrincipalFromSessionKeyMode, c1 as PrincipalRule, c2 as ProceduralConfig, aq as ProvenanceConfig, ar as ProvenanceSource, aj as QmdSearchExplain, Q as QmdSearchResult, c3 as QuestionEntry, a$ as RECALL_DISCLOSURE_LEVELS, c4 as ReasoningEffort, K as RecallDisclosure, c5 as RecallPipelineConfig, H as RecallPlanMode, c6 as RecallSectionConfig, R as RecallTierExplain, c7 as RecallTraceEvent, c8 as RelevanceFeedback, as as RetrievalTier, c9 as SPECULATIVE_TTL_DAYS, ca as ScopeProfileAutoPromoteConfig, cb as ScopeProfileConfig, av as ScopeProfileLayerId, aw as ScopeProfilePromotionTarget, cc as ScopeProfileTeamProjectConfig, cd as ScopeTeamConfig, ce as ScoredEntity, a6 as SecretRef, cf as SemanticChunkingConfigShape, a1 as SessionObserverBandConfig, cg as SignalLevel, at as SignalScanResult, ch as SlotBehaviorConfig, ci as SlotMismatchMode, T as TopicScore, _ as TranscriptEntry, cj as TriggerMode, a3 as VerificationState, ck as confidenceTier, b5 as isRecallDisclosure } from './types-Dm5xxVrr.js';
+export { y as AccessTrackingEntry, A as ActiveRecallChatType, d as ActiveRecallModelFallbackPolicy, b as ActiveRecallPromptStyle, a as ActiveRecallQueryMode, c as ActiveRecallThinking, a7 as AgentAccessAuthToken, b6 as AgentAccessHttpConfig, b7 as AgentDefaultsConfig, b8 as AgentPersona, f as AgentPersonaModelConfig, b9 as BehaviorLoopAdjustment, e as BehaviorLoopPolicyState, ba as BehaviorSignalDirection, B as BehaviorSignalEvent, bb as BehaviorSignalType, aL as BootstrapOptions, aM as BootstrapResult, W as BriefingActiveThread, bc as BriefingCalendarSourceError, aS as BriefingConfig, S as BriefingFocus, O as BriefingFollowup, aT as BriefingOpenCommitment, Y as BriefingRecentEntity, X as BriefingResult, N as BriefingSections, aU as BriefingWindow, bd as BufferEntryState, k as BufferState, o as BufferSurpriseEvent, Z as BufferTurn, V as CalendarEvent, U as CalendarSource, be as CaptureMode, $ as Checkpoint, bf as CodexCliReasoningEffort, bg as CodexCompactionFlushMode, aV as CodexCompatConfig, bh as CodexConnectorConfig, aK as CodingContext, bi as CodingKnowledgeConfig, aP as CodingModeConfig, bj as CompressionGuidelineActivationState, a9 as CompressionGuidelineOptimizerActionSummary, a8 as CompressionGuidelineOptimizerEventCounts, aa as CompressionGuidelineOptimizerRuleUpdate, bk as CompressionGuidelineOptimizerSourceWindow, C as CompressionGuidelineOptimizerState, bl as ConfidenceTier, bm as ConsolidationAction, bn as ConsolidationItem, aN as ConsolidationObservation, ag as ConsolidationResult, s as ContinuityImprovementLoop, r as ContinuityIncidentCloseInput, p as ContinuityIncidentOpenInput, q as ContinuityIncidentRecord, bo as ContinuityIncidentState, bp as ContinuityLoopCadence, u as ContinuityLoopReviewInput, bq as ContinuityLoopStatus, t as ContinuityLoopUpsertInput, br as ContradictionScanConfig, au as ConversationThread, bs as CronConversationRecallMode, bt as CronRecallMode, aW as DEFAULT_RECALL_DISCLOSURE, ah as DaySummaryResult, bu as DreamingConfig, bv as DreamingNarrativePromptStyle, bw as DreamsDeepSleepConfig, bx as DreamsLightSleepConfig, ay as DreamsPhase, by as DreamsPhaseStatus, bz as DreamsPhasesConfig, bA as DreamsRemConfig, az as DreamsRunResult, ax as DreamsStatusResult, bB as EngramTraceEvent, w as EntityActivityEntry, x as EntityFile, ac as EntityMention, v as EntityRelationship, ad as EntitySchemaDefinition, ae as EntitySchemaSectionDefinition, E as EntityStructuredSection, aO as EntityTimelineEntry, aX as ExtractedFact, bC as ExtractedProcedureStep, bD as ExtractedQuestion, bE as ExtractedReasoningTrace, bF as ExtractedReasoningTraceStep, bG as ExtractedRelationship, bH as ExtractionPassSource, af as ExtractionResult, F as FileHygieneConfig, G as GatewayConfig, bI as GitHubLiveConnectorConfig, bJ as GmailLiveConnectorConfig, bK as GoogleDriveLiveConnectorConfig, bL as HeartbeatConfig, bM as HeartbeatDetectionMode, a0 as HourlySummary, J as IdentityInjectionMode, a5 as ImportanceLevel, I as ImportanceScore, a2 as LifecycleState, L as LiveConnectorsConfig, bN as LlmTraceCallback, bO as LlmTraceEvent, ak as MemoryActionEligibilityContext, aY as MemoryActionEligibilitySource, m as MemoryActionEvent, bP as MemoryActionOutcome, bQ as MemoryActionPolicyDecision, al as MemoryActionPolicyResult, bR as MemoryActionStatus, ab as MemoryActionType, M as MemoryCategory, g as MemoryFile, j as MemoryFrontmatter, ai as MemoryIntent, n as MemoryLifecycleEvent, am as MemoryLifecycleEventType, an as MemoryLifecycleStateSummary, i as MemoryLink, bS as MemoryLinkType, aZ as MemoryObservation, bT as MemoryOsPresetName, z as MemoryProjectionCurrentState, a_ as MemoryScope, h as MemoryStatus, D as MemorySummary, l as MetaState, bU as ModelApi, bV as ModelDefinitionConfig, bW as ModelProviderAuthMode, ao as ModelProviderConfig, bX as NamespacePolicy, ap as NativeKnowledgeConfig, bY as NativeKnowledgeFolderRuleConfig, bZ as NativeKnowledgeObsidianVaultConfig, b_ as NativeKnowledgeOpenClawWorkspaceConfig, b$ as NotionLiveConnectorConfig, P as PluginConfig, a4 as PolicyClass, c0 as PrincipalFromSessionKeyMode, c1 as PrincipalRule, c2 as ProceduralConfig, aq as ProvenanceConfig, ar as ProvenanceSource, aj as QmdSearchExplain, Q as QmdSearchResult, c3 as QuestionEntry, a$ as RECALL_DISCLOSURE_LEVELS, c4 as ReasoningEffort, K as RecallDisclosure, c5 as RecallPipelineConfig, H as RecallPlanMode, c6 as RecallSectionConfig, R as RecallTierExplain, c7 as RecallTraceEvent, c8 as RelevanceFeedback, as as RetrievalTier, c9 as SPECULATIVE_TTL_DAYS, ca as ScopeProfileAutoPromoteConfig, cb as ScopeProfileConfig, av as ScopeProfileLayerId, aw as ScopeProfilePromotionTarget, cc as ScopeProfileTeamProjectConfig, cd as ScopeTeamConfig, ce as ScoredEntity, a6 as SecretRef, cf as SemanticChunkingConfigShape, a1 as SessionObserverBandConfig, cg as SignalLevel, at as SignalScanResult, ch as SlotBehaviorConfig, ci as SlotMismatchMode, T as TopicScore, _ as TranscriptEntry, cj as TriggerMode, a3 as VerificationState, ck as confidenceTier, b5 as isRecallDisclosure } from './types-2NoBoRBM.js';

package/dist/types.js

@@ -4,7 +4,7 @@ import {
   SPECULATIVE_TTL_DAYS,
   confidenceTier,
   isRecallDisclosure
-} from "./chunk-NGFEWFNK.js";
+} from "./chunk-DQHZA7Y3.js";
 import "./chunk-PZ5AY32C.js";
 export {
   DEFAULT_RECALL_DISCLOSURE,

package/dist/utility-runtime.d.ts

@@ -1,5 +1,5 @@
 import { TierRoutingPolicy } from './tier-routing.js';
-import './types-Dm5xxVrr.js';
+import './types-2NoBoRBM.js';
 import './types-ByK7T3L6.js';
 import './index-DJ9QWMw-.js';
 import './lifecycle.js';

package/dist/verified-recall.js

@@ -1,22 +1,23 @@
 import {
   compareVerifiedEpisodeResults,
   searchVerifiedEpisodes
-} from "./chunk-4FE2K57M.js";
+} from "./chunk-3VVH6ZQW.js";
 import "./chunk-7FL4CNPV.js";
-import "./chunk-BLIWOONZ.js";
+import "./chunk-VFVG4NS2.js";
 import "./chunk-M7XQSUBB.js";
 import "./chunk-5UZXUTVO.js";
 import "./chunk-5GPPACXK.js";
+import "./chunk-SVOZFLIQ.js";
 import "./chunk-J6A3CX5N.js";
-import "./chunk-NGFEWFNK.js";
+import "./chunk-DQHZA7Y3.js";
+import "./chunk-SCU65EZI.js";
 import "./chunk-MB5RSUW6.js";
 import "./chunk-6KYMPV2O.js";
 import "./chunk-AWJ2FHCF.js";
 import "./chunk-42JKGUFJ.js";
 import "./chunk-RULE4VG5.js";
-import "./chunk-SCU65EZI.js";
-import "./chunk-DM2T26WE.js";
 import "./chunk-LDXUBPMO.js";
+import "./chunk-DM2T26WE.js";
 import "./chunk-FVQJYWH7.js";
 import "./chunk-G7D6GZ5J.js";
 import "./chunk-VF4XKTX3.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.3.689",
+  "version": "9.3.691",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -2931,7 +2931,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.3.689"
+    "@remnic/coding-graph": "^9.3.691"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/access-boundary.ts

@@ -34,7 +34,8 @@ export type OperationName =
   | "memory_get"
   | "memory_search"
   | "memory_store"
-  | "coding_decision";
+  | "coding_decision"
+  | "coding_architecture";
 
 // ---------------------------------------------------------------------------
 // Operation context — what every handler receives

package/src/access-cli.test.ts

@@ -522,3 +522,43 @@ test("access-cli rejects adjacent option-looking values", async () => {
 
   assert.match(output, /missing required option: --content/);
 });
+
+// ──────────────────────────────────────────────────────────────────────────
+// architecture command — wired through the boundary operation (#1548 PR3)
+// ──────────────────────────────────────────────────────────────────────────
+
+test("access-cli architecture is a known command (unknown options rejected, not unsupported-command)", async () => {
+  const output = await captureRunCliFailure(["architecture", "--typo", "x"]);
+  assert.match(output, /unknown option: --typo/);
+});
+
+test("access-cli architecture accepts its documented value options", async () => {
+  // Valid option spellings parse cleanly; the invocation only fails once it
+  // reaches the runtime (no OpenClaw config here), proving the options were
+  // accepted by parseArgs rather than rejected as unknown.
+  const output = await captureRunCliFailure([
+    "architecture",
+    "--subcommand",
+    "get",
+    "--session-key",
+    "s1",
+    "--namespace",
+    "ns",
+    "--project-tag",
+    "myproj",
+  ]);
+  assert.doesNotMatch(output, /unknown option/);
+  assert.doesNotMatch(output, /unsupported command/);
+});
+
+test("access-cli usage lists the architecture command and its options", async () => {
+  const output = await captureRunCliFailure(["architecture", "--typo"]);
+  assert.match(output, /engram-access architecture \[options\]/);
+  assert.match(output, /Architecture options:/);
+  assert.match(output, /--subcommand <get\|refresh>/);
+});
+
+test("access-cli still rejects truly unknown commands as unsupported", async () => {
+  const output = await captureRunCliFailure(["bogus-command"]);
+  assert.match(output, /unsupported command/);
+});

package/src/access-cli.ts

@@ -15,7 +15,7 @@ import { projectTagProjectId } from "./coding/coding-namespace.js";
 
 const OPENCLAW_REMNIC_PLUGIN_IDS = ["openclaw-remnic", "openclaw-engram"] as const;
 
-type CommandName = "browse" | "store" | "decision";
+type CommandName = "browse" | "store" | "decision" | "architecture";
 
 type ParsedArgs = {
   command: CommandName;
@@ -137,6 +137,7 @@ function usage(): string {
     "  engram-access browse [options]",
     "  engram-access store [options]",
     "  engram-access decision [options]",
+    "  engram-access architecture [options]",
     "",
     "Browse options:",
     "  --namespace <name>",
@@ -176,6 +177,14 @@ function usage(): string {
     "  --entity-ref <ref> (repeatable)",
     "  --project-tag <tag> (attach coding context for this invocation)",
     "  --supersedes-id <id> (alias for --id on supersede)",
+    "",
+    "Architecture options:",
+    "  --subcommand <get|refresh>",
+    "  --namespace <name>",
+    "  --session-key <key>",
+    "  --principal <principal>",
+    "  --project-tag <tag> (attach coding context for this invocation)",
+    "  --repo-root <path> (repo to scan for refresh; defaults to the current directory)",
   ].join("\n");
 }
 
@@ -228,6 +237,17 @@ const COMMAND_SPECS: Record<CommandName, CommandSpec> = {
     ]),
     flagOptions: new Set(),
   },
+  architecture: {
+    valueOptions: new Set([
+      "subcommand",
+      "namespace",
+      "session-key",
+      "principal",
+      "project-tag",
+      "repo-root",
+    ]),
+    flagOptions: new Set(),
+  },
 };
 const BROWSE_SORT_VALUES = Object.freeze([
   "updated_desc",
@@ -238,9 +258,19 @@ const BROWSE_SORT_VALUES = Object.freeze([
 
 type BrowseSort = (typeof BROWSE_SORT_VALUES)[number];
 
+/**
+ * Type guard for {@link CommandName}. Enumerating the union (rather than a
+ * bare `value in COMMAND_SPECS`) is what lets TypeScript NARROW the string
+ * to `CommandName` — the `in` operator alone yields TS2322 on the
+ * `command: commandRaw` assignment below (codex review P2).
+ */
+function isCommandName(value: string): value is CommandName {
+  return value === "browse" || value === "store" || value === "decision" || value === "architecture";
+}
+
 function parseArgs(argv: string[]): ParsedArgs {
   const [commandRaw, ...rest] = argv;
-  if (commandRaw !== "browse" && commandRaw !== "store" && commandRaw !== "decision") {
+  if (!isCommandName(commandRaw)) {
     throw new UsageError("unsupported-command");
   }
   const spec = COMMAND_SPECS[commandRaw];
@@ -552,6 +582,60 @@ async function runDecision(args: ParsedArgs, preferredId?: string): Promise<void
   console.log(JSON.stringify(output.result, null, 2));
 }
 
+/**
+ * Architecture-card surface (issue #1548 Track A PR 3). Dispatches through
+ * the same `coding_architecture` operation as the MCP tool and HTTP route —
+ * one validation boundary, three transports.
+ */
+async function runArchitecture(args: ParsedArgs, preferredId?: string): Promise<void> {
+  const subcommand = requireOption(args, "subcommand");
+  const { config, service } = buildRuntime(preferredId);
+  // Same coding-context attachment as runDecision (review P2): the CLI's
+  // fresh Orchestrator has an empty session coding-context map, so attach
+  // a context BEFORE dispatching when --project-tag + --session-key are
+  // given, so the gate passes and writes resolve to the right namespace.
+  const projectTag = getLastOption(args, "project-tag");
+  const sessionKey = getLastOption(args, "session-key");
+  if (sessionKey && sessionKey.trim().length > 0) {
+    // refresh scans codingContext.rootPath, so it must be a REAL checkout
+    // path. Default to the CWD (or an explicit --repo-root) so a one-shot
+    // CLI refresh scans the caller's repo, not a non-existent tag path.
+    const repoRoot = expandOptionalPath(getLastOption(args, "repo-root")) ?? process.cwd();
+    // --project-tag supplies the context id (namespace); when absent, derive
+    // a default from the repo-root basename so refresh works with just
+    // --session-key + --repo-root (codex review).
+    const projectId =
+      projectTag && projectTag.trim().length > 0
+        ? projectTagProjectId(projectTag.trim())
+        : projectTagProjectId(path.basename(repoRoot));
+    service.setCodingContext({
+      sessionKey,
+      codingContext: {
+        projectId,
+        branch: null,
+        rootPath: repoRoot,
+        defaultBranch: null,
+      },
+    });
+  }
+  const op = getOperation("coding_architecture");
+  if (!op) {
+    throw new Error("access-boundary: operation not registered: coding_architecture");
+  }
+  const output = (await op.run(
+    {
+      subcommand,
+      namespace: getLastOption(args, "namespace"),
+      sessionKey,
+    },
+    {
+      service,
+      authenticatedPrincipal: getLastOption(args, "principal") ?? config.agentAccessHttp.principal,
+    },
+  )) as { result: unknown };
+  console.log(JSON.stringify(output.result, null, 2));
+}
+
 export async function main(
   argv: string[] = process.argv.slice(2),
   options: AccessCliOptions = {},
@@ -565,6 +649,10 @@ export async function main(
     await runDecision(args, options.preferredId);
     return;
   }
+  if (args.command === "architecture") {
+    await runArchitecture(args, options.preferredId);
+    return;
+  }
   await runStore(args, options.preferredId);
 }
 

package/src/access-http.ts

@@ -316,6 +316,7 @@ export class EngramAccessHttpServer {
       citationsAutoDetect: options.citationsAutoDetect,
       emitLegacyTools: options.emitLegacyTools,
       codingDecisionVisible: this.service.decisionRecordSurfaceVisible,
+      architectureCardVisible: this.service.architectureCardSurfaceVisible,
     });
   }
 
@@ -1361,6 +1362,30 @@ export class EngramAccessHttpServer {
       return;
     }
 
+    if (req.method === "POST" && pathname === "/engram/v1/coding/architecture") {
+      // Migrated through the access boundary (issue #1525/#1548 PR3):
+      // refresh persists the card, so it is gated by the 30/min write quota;
+      // get is a pure read and stays uncounted.
+      const body = await this.readJsonBody(req);
+      const isWriteSubcommand = body.subcommand === "refresh";
+      if (isWriteSubcommand) {
+        this.ensureWriteRateLimitAvailable();
+      }
+      const op = getOperation("coding_architecture");
+      if (!op) {
+        throw new EngramAccessInputError("access-boundary: operation not registered: coding_architecture");
+      }
+      const output = (await op.run(body, {
+        service: this.service,
+        authenticatedPrincipal: this.resolveRequestPrincipal(req),
+      })) as { result: unknown };
+      if (isWriteSubcommand) {
+        this.recordWriteRateLimitHit();
+      }
+      this.respondJson(res, 200, output.result);
+      return;
+    }
+
     if (req.method === "POST" && pathname === "/engram/v1/suggestions") {
       const body = await this.readValidatedBody(req, "suggestionSubmit");
       const request = {
@@ -2213,13 +2238,16 @@ export class EngramAccessHttpServer {
       typeof toolArgs === "object" &&
       !Array.isArray(toolArgs) &&
       (toolArgs as { dryRun?: unknown }).dryRun === true;
+    const toolArgsSubcommand =
+      toolArgs !== null && typeof toolArgs === "object" && !Array.isArray(toolArgs) && "subcommand" in toolArgs
+        ? toolArgs.subcommand
+        : undefined;
     const codingDecisionWrite =
       (toolName === "engram.coding_decision" || toolName === "remnic.coding_decision") &&
-      toolArgs !== null &&
-      typeof toolArgs === "object" &&
-      !Array.isArray(toolArgs) &&
-      ((toolArgs as { subcommand?: unknown }).subcommand === "record" ||
-        (toolArgs as { subcommand?: unknown }).subcommand === "supersede");
+      (toolArgsSubcommand === "record" || toolArgsSubcommand === "supersede");
+    const codingArchitectureWrite =
+      (toolName === "engram.coding_architecture" || toolName === "remnic.coding_architecture") &&
+      toolArgsSubcommand === "refresh";
     const isMcpWrite =
       request.method === "tools/call" &&
       (
@@ -2248,7 +2276,8 @@ export class EngramAccessHttpServer {
             toolName === "remnic.memory_action_apply"
           )
         ) ||
-        codingDecisionWrite
+        codingDecisionWrite ||
+        codingArchitectureWrite
       );
     if (isMcpWrite) {
       this.ensureWriteRateLimitAvailable();

package/src/access-mcp.ts

@@ -110,6 +110,7 @@ const MCP_MIGRATED_OPERATIONS: Readonly<Record<string, OperationName>> = {
   "engram.memory_search": "memory_search",
   "engram.memory_store": "memory_store",
   "engram.coding_decision": "coding_decision",
+  "engram.coding_architecture": "coding_architecture",
 };
 
 function resolveChatGptInspectorRecallSessionKey(
@@ -324,6 +325,12 @@ export class EngramMcpServer {
    * pre-feature.
    */
   private readonly codingDecisionVisible: boolean;
+  /**
+   * Whether the `coding_architecture` tool should appear in `tools/list`.
+   * Gated on `codingKnowledge.enabled && codingKnowledge.architectureCard`
+   * (issue #1548 Track A PR 3, rule 39).
+   */
+  private readonly architectureCardVisible: boolean;
 
   constructor(
     private readonly service: EngramAccessService,
@@ -333,12 +340,14 @@ export class EngramMcpServer {
       citationsAutoDetect?: boolean;
       emitLegacyTools?: boolean;
       codingDecisionVisible?: boolean;
+      architectureCardVisible?: boolean;
     } = {},
   ) {
     this.citationsEnabled = options.citationsEnabled === true;
     this.citationsAutoDetect = options.citationsAutoDetect !== false;
     this.emitLegacyTools = options.emitLegacyTools !== false;
     this.codingDecisionVisible = options.codingDecisionVisible === true;
+    this.architectureCardVisible = options.architectureCardVisible === true;
     this.authenticatedPrincipal =
       options.principal?.trim() ||
       readEnvVar("OPENCLAW_ENGRAM_ACCESS_PRINCIPAL")?.trim() ||
@@ -1999,6 +2008,31 @@ export class EngramMcpServer {
       );
       this.tools = [...this.tools, ...codingDecisionTools];
     }
+    if (this.architectureCardVisible) {
+      const architectureTools = withToolAliases(
+        {
+          name: "engram.coding_architecture",
+          description:
+            "Get or refresh the architecture card for the session's coding namespace (issue #1548 Track A PR 3). Subcommands: get, refresh.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              subcommand: {
+                type: "string",
+                enum: ["get", "refresh"],
+                description: "Which architecture-card operation to run.",
+              },
+              sessionKey: { type: "string", description: "Session identifier whose coding context scopes the operation." },
+              namespace: { type: "string", description: "Optional explicit namespace (overrides coding-context overlay)." },
+            },
+            required: ["subcommand"],
+            additionalProperties: false,
+          },
+        },
+        this.emitLegacyTools,
+      );
+      this.tools = [...this.tools, ...architectureTools];
+    }
   }
 
   /** Get clientInfo for a specific MCP session. Returns undefined for non-MCP requests. */

package/src/access-operations.ts

@@ -25,6 +25,10 @@ import {
   type DecisionSurfaceRequest,
   type DecisionSurfaceResponse,
 } from "./coding/decision-surfaces.js";
+import {
+  type ArchitectureSurfaceRequest,
+  type ArchitectureSurfaceResponse,
+} from "./coding/architecture-surfaces.js";
 
 // ---------------------------------------------------------------------------
 // memory_get — fetch one memory by id
@@ -206,6 +210,46 @@ export const codingDecisionOperation = defineOperation<
   },
 });
 
+// ---------------------------------------------------------------------------
+// coding_architecture — architecture-card surfaces (issue #1548 Track A PR 3)
+// ---------------------------------------------------------------------------
+
+const codingArchitectureSchema = z.preprocess(
+  (data) => {
+    if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+      const obj = data as Record<string, unknown>;
+      const cleaned: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(obj)) {
+        if (value !== null) cleaned[key] = value;
+      }
+      return cleaned;
+    }
+    return data;
+  },
+  z.object({
+    subcommand: z.enum(["get", "refresh"]),
+    sessionKey: z.string().optional(),
+    namespace: z.string().optional(),
+  }),
+);
+
+export type CodingArchitectureInput = ArchitectureSurfaceRequest;
+export type CodingArchitectureOutput = { result: ArchitectureSurfaceResponse };
+
+export const codingArchitectureOperation = defineOperation<
+  CodingArchitectureInput,
+  CodingArchitectureOutput
+>({
+  name: "coding_architecture",
+  description:
+    "Get or refresh the architecture card for the session's coding namespace (issue #1548 Track A PR 3).",
+  schema: codingArchitectureSchema as z.ZodType<CodingArchitectureInput>,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codingArchitecture(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
 // ---------------------------------------------------------------------------
 // Surface registration map — what each transport calls the pilot ops
 // ---------------------------------------------------------------------------
@@ -220,4 +264,5 @@ export const REGISTERED_OPERATIONS = [
   memorySearchOperation.spec.name,
   memoryStoreOperation.spec.name,
   codingDecisionOperation.spec.name,
+  codingArchitectureOperation.spec.name,
 ] as const;

package/src/access-service.ts

@@ -19,6 +19,16 @@ import {
   type DecisionSurfaceRequest,
   type DecisionSurfaceResponse,
 } from "./coding/decision-surfaces.js";
+import {
+  handleCodingArchitecture,
+  type ArchitectureSurfaceRequest,
+  type ArchitectureSurfaceResponse,
+  type ArchitectureSurfaceStorage,
+  createArchitectureVersioningHook,
+  ARCHITECTURE_CARD_TAG,
+} from "./coding/architecture-surfaces.js";
+import { buildArchitectureCard, createArchitectureCardSummariser } from "./coding/architecture-card.js";
+import { createVersion } from "./page-versioning.js";
 import { WorkStorage } from "./work/storage.js";
 import {
   exportWorkBoardMarkdown,
@@ -4485,6 +4495,56 @@ export class EngramAccessService {
     });
   }
 
+  /** Whether the coding_architecture tool should appear in tools/list (rule 39). */
+  get architectureCardSurfaceVisible(): boolean {
+    return this.orchestrator.config.codingKnowledge?.enabled === true
+      && this.orchestrator.config.codingKnowledge?.architectureCard === true;
+  }
+  /**
+   * Thin delegate — handler logic in coding/architecture-surfaces.ts (#1548 PR3).
+   * All three surfaces (MCP/HTTP/CLI) arrive here via the boundary operation.
+   * Namespace resolution uses the SAME coding-scoped path as decision records.
+   */
+  async codingArchitecture(
+    request: ArchitectureSurfaceRequest,
+    authenticatedPrincipal?: string,
+  ): Promise<ArchitectureSurfaceResponse> {
+    const resolvedConfig = this.orchestrator.config;
+    return handleCodingArchitecture(request, {
+      codingKnowledge: this.orchestrator.config.codingKnowledge,
+      getCodingContext: (sk) => this.orchestrator.getCodingContextForSession(sk),
+      resolveStorage: async (req) => {
+        const isWrite = req.subcommand === "refresh";
+        const ns = isWrite
+          ? await this.resolveCodingScopedWriteNamespace({
+              namespace: req.namespace,
+              sessionKey: req.sessionKey,
+              authenticatedPrincipal,
+            })
+        : await this.resolveCodingScopedReadableNamespace({
+            namespace: req.namespace,
+            sessionKey: req.sessionKey,
+            authenticatedPrincipal,
+          });
+        const storage = await this.orchestrator.getStorage(ns);
+        return Object.assign(storage, { namespace: ns }) as ArchitectureSurfaceStorage;
+      },
+      buildCard: async (repoRoot) => buildArchitectureCard(repoRoot, {
+        llmSummary: this.orchestrator.config.codingKnowledge?.architectureCardLlmSummary === true,
+        summariser: createArchitectureCardSummariser(this.fallbackLlmRef ?? this.localLlmRef),
+      }),
+      versioning: createArchitectureVersioningHook(
+        resolvedConfig.versioningEnabled === true,
+        resolvedConfig.versioningMaxPerPage,
+        resolvedConfig.versioningSidecarDir,
+        resolvedConfig.memoryDir,
+        (p) => nodeFs.readFile(p, "utf-8"),
+        createVersion,
+      ),
+      throwInputError: (msg) => { throw new EngramAccessInputError(msg); },
+    });
+  }
+
   async memoryBrowse(
     request: EngramAccessMemoryBrowseRequest = {},
   ): Promise<EngramAccessMemoryBrowseResponse> {