@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.5

package/apps/client-cms-editor/reference/DONOR_tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": ["backend/src/**/*", "frontend/src/**/*", "frontend/src/env.d.ts"]
+}

package/apps/client-cms-editor/shared/cms/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@inneranimalmedia/agentsam-cms-shared",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./publication": "./src/publication.ts",
+    "./bindings": "./src/cloudflare-bindings.ts",
+    "./context": "./src/agent-context.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@inneranimalmedia/agentsam-contracts": "file:../../../../packages/agentsam-contracts"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/apps/client-cms-editor/shared/cms/src/agent-context.ts

@@ -0,0 +1,35 @@
+import type { AgentContext, AgentContextProvider, AgentPrincipal } from '@inneranimalmedia/agentsam-contracts';
+
+export type CmsAgentContextInput = {
+  principal: AgentPrincipal;
+  projectId: string;
+  route?: string;
+  pageId?: string | null;
+  sectionId?: string | null;
+  blockId?: string | null;
+  publicationRevision?: number | null;
+};
+
+export function createCmsAgentContext(input: CmsAgentContextInput): AgentContext {
+  return {
+    surface: 'cms',
+    accountId: input.principal.accountId,
+    authUserId: input.principal.authUserId,
+    projectId: input.projectId,
+    metadata: {
+      route: input.route ?? null,
+      pageId: input.pageId ?? null,
+      sectionId: input.sectionId ?? null,
+      blockId: input.blockId ?? null,
+      publicationRevision: input.publicationRevision ?? null,
+    },
+  };
+}
+
+export function createCmsAgentContextProvider(getInput: () => CmsAgentContextInput | Promise<CmsAgentContextInput>): AgentContextProvider {
+  return {
+    async getContext() {
+      return createCmsAgentContext(await getInput());
+    },
+  };
+}

package/apps/client-cms-editor/shared/cms/src/cloudflare-bindings.ts

@@ -0,0 +1,51 @@
+export type CmsCloudflareCapability =
+  | 'cms-cloud'
+  | 'iam'
+  | 'workers-ai'
+  | 'browser'
+  | 'container'
+  | 'encrypted-secrets'
+  | 'acp';
+
+export type CmsCloudflareBindingName =
+  | 'DB'
+  | 'WEBSITE_ASSETS'
+  | 'SESSION_CACHE'
+  | 'AGENTSAM_WAI'
+  | 'MY_CONTAINER'
+  | 'MYBROWSER'
+  | 'IAM_CLIENT_ID'
+  | 'IAM_CLIENT_SECRET'
+  | 'IAM_ORIGIN'
+  | 'SECRETS_ENCRYPTION_KEY'
+  | 'ACP_CLIENT_ID'
+  | 'ACP_CLIENT_SECRET';
+
+export type CmsCloudflareBindingContract = {
+  name: CmsCloudflareBindingName;
+  capability: CmsCloudflareCapability;
+  required: boolean;
+  secret?: boolean;
+  authority: 'metadata' | 'assets' | 'identity' | 'cache-only' | 'execution-only' | 'configuration';
+  description: string;
+};
+
+export const CMS_CLOUDFLARE_BINDINGS: readonly CmsCloudflareBindingContract[] = [
+  { name: 'DB', capability: 'cms-cloud', required: true, authority: 'metadata', description: 'D1 authority for CMS/account/publication metadata.' },
+  { name: 'WEBSITE_ASSETS', capability: 'cms-cloud', required: true, authority: 'assets', description: 'R2 storage for CMS-managed media, theme assets, generated artifacts and publication snapshots.' },
+  { name: 'SESSION_CACHE', capability: 'cms-cloud', required: false, authority: 'cache-only', description: 'Optional session/login acceleration cache. Never account or session authority.' },
+  { name: 'IAM_CLIENT_ID', capability: 'iam', required: true, authority: 'configuration', description: 'Public IAM client identifier.' },
+  { name: 'IAM_CLIENT_SECRET', capability: 'iam', required: true, secret: true, authority: 'identity', description: 'Confidential IAM client credential.' },
+  { name: 'IAM_ORIGIN', capability: 'iam', required: true, authority: 'identity', description: 'Canonical IAM issuer/auth-service origin, not the current website origin by default.' },
+  { name: 'AGENTSAM_WAI', capability: 'workers-ai', required: true, authority: 'execution-only', description: 'Workers AI binding when the user opts into Cloudflare AI.' },
+  { name: 'MYBROWSER', capability: 'browser', required: true, authority: 'execution-only', description: 'Optional Browser Rendering / browser automation binding.' },
+  { name: 'MY_CONTAINER', capability: 'container', required: true, authority: 'execution-only', description: 'Optional scoped execution runtime. It receives authenticated identity; it never establishes identity.' },
+  { name: 'SECRETS_ENCRYPTION_KEY', capability: 'encrypted-secrets', required: true, secret: true, authority: 'configuration', description: 'Envelope-encryption key only where application-managed encrypted secrets are persisted.' },
+  { name: 'ACP_CLIENT_ID', capability: 'acp', required: true, authority: 'configuration', description: 'ACP client identity when ACP is enabled.' },
+  { name: 'ACP_CLIENT_SECRET', capability: 'acp', required: true, secret: true, authority: 'configuration', description: 'ACP confidential credential when ACP is enabled.' },
+] as const;
+
+export function cmsBindingsForCapabilities(capabilities: Iterable<CmsCloudflareCapability>) {
+  const enabled = new Set(capabilities);
+  return CMS_CLOUDFLARE_BINDINGS.filter((binding) => enabled.has(binding.capability));
+}

package/apps/client-cms-editor/shared/cms/src/editor-types.ts

@@ -0,0 +1,58 @@
+export type CmsEditorZone = 'HEADER' | 'BODY' | 'FOOTER' | 'TEMPLATE';
+export type CmsEditorStatus = 'live' | 'draft' | 'new';
+export type CmsEditorTargetKind = 'page' | 'section' | 'block';
+
+export type CmsEditorBlock = {
+  id: string;
+  sectionId: string;
+  type: string;
+  visible: boolean;
+  data: Record<string, any>;
+  sortOrder: number;
+};
+
+export type CmsEditorSection = {
+  id: string;
+  name: string;
+  type: string;
+  zone: CmsEditorZone;
+  visible: boolean;
+  color: string;
+  fields: Record<string, any>;
+  css?: Record<string, any>;
+  blocks: CmsEditorBlock[];
+};
+
+export type CmsEditorPage = {
+  id: string;
+  title: string;
+  slug: string;
+  status: CmsEditorStatus;
+  type: string;
+  parent?: string;
+  sections: CmsEditorSection[];
+  metaTitle: string;
+  metaDescription: string;
+};
+
+export type CmsEditorSite = {
+  id: string;
+  name: string;
+  initials: string;
+  domain: string;
+  edited: string;
+  color: string;
+  pages: CmsEditorPage[];
+};
+
+export type CmsEditorSelection = {
+  kind: CmsEditorTargetKind;
+  pageId: string | null;
+  sectionId: string | null;
+  blockId: string | null;
+  fieldPath: string | null;
+};
+
+export const emptyCmsEditorSelection = (): CmsEditorSelection => ({
+  kind: 'page', pageId: null, sectionId: null, blockId: null, fieldPath: null,
+});

package/apps/client-cms-editor/shared/cms/src/index.ts

@@ -0,0 +1,5 @@
+export * from './editor-types';
+export * from './publication';
+export * from './cloudflare-bindings';
+export * from './agent-context';
+export * from './routes';

package/apps/client-cms-editor/shared/cms/src/publication.ts

@@ -0,0 +1,24 @@
+export type CmsSectionPayload = {
+  id?: string;
+  type: string;
+  props: Record<string, unknown>;
+};
+
+export type CmsPublicationSnapshot = {
+  publicationId: string;
+  route: string;
+  revision: number;
+  theme: string;
+  sections: CmsSectionPayload[];
+  publishedAt?: string;
+  metadata?: Record<string, unknown>;
+};
+
+export type CmsPublishedAsset = {
+  id: string;
+  key: string;
+  mimeType: string;
+  size?: number;
+  url?: string;
+  metadata?: Record<string, unknown>;
+};

package/apps/client-cms-editor/shared/cms/src/routes.ts

@@ -0,0 +1,11 @@
+export const CMS_ROUTE_BOUNDARIES = Object.freeze({
+  public: '/*',
+  auth: '/auth/*',
+  dashboard: '/dashboard/*',
+  agentsam: '/agentsam',
+  cms: '/cms',
+  publicApi: '/api/public/*',
+  authApi: '/api/auth/*',
+  cmsApi: '/api/cms/*',
+  agentsamApi: '/api/agentsam/*',
+});

package/apps/client-cms-editor/shared/cms/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/bin/agentsam-rapid-rust

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+const args = process.argv.slice(2);
+const candidates = [
+  process.env.AGENTSAM_RAPID_RUST_BIN,
+  path.join(os.homedir(), '.agentsam', 'bin', 'agentsam-rapid-rust-native'),
+  path.join(root, 'packages', 'agentsam-rapid-rust', 'target', 'release', 'agentsam-rapid-rust'),
+].filter(Boolean);
+
+for (const candidate of candidates) {
+  if (fs.existsSync(candidate)) {
+    const result = spawnSync(candidate, args, { stdio: 'inherit' });
+    process.exit(result.status ?? 1);
+  }
+}
+
+const manifest = path.join(root, 'packages', 'agentsam-rapid-rust', 'Cargo.toml');
+if (!fs.existsSync(manifest)) {
+  console.error('AgentSam Rapid Rust source is missing from this installation.');
+  process.exit(2);
+}
+const cargo = spawnSync('cargo', ['--version'], { stdio: 'ignore' });
+if (cargo.status !== 0) {
+  console.error('Rust/Cargo is required. Install Rust, then run: agentsam rust doctor');
+  process.exit(2);
+}
+console.error('AgentSam Rapid Rust native binary is not installed; compiling local CLI source…');
+const result = spawnSync('cargo', ['run', '--quiet', '--manifest-path', manifest, '--', ...args], { stdio: 'inherit' });
+process.exit(result.status ?? 1);

package/docs/AUTH_IDENTITY_CONTRACT.md

@@ -2,6 +2,8 @@
 
 The `agentsam-sdk` package owns the portable public configuration contract. Consuming applications implement storage, authorization, and host routes against this contract instead of defining competing environment names.
 
+Full env naming / alias / storage law: [`docs/contracts/environment-vocabulary.md`](./contracts/environment-vocabulary.md).
+
 ## Canonical variables
 
 | Variable | Meaning |

package/docs/MACHINE_INTELLIGENCE.md

@@ -0,0 +1,120 @@
+# Machine Intelligence — AgentSam ladder
+
+**Status:** Scaffold for Batches A–D (2026-09-24 plans).  
+**Authority:** `AGENTSAM.md` · work orders in `docs/plans/UNIVERSAL-INGEST-MACHINE-FIRST-2026-09-24.md` and `docs/plans/MACHINE-FIRST-APPS-TUI-2026-09-24.md`.
+
+**Intent:** Audit and strengthen worlds in place. Do not redesign the repo around package purity. Proof = real `apps/*` + harvested sites — not toy demos.
+
+---
+
+## Product scales (MINI / APP / WORLD)
+
+```text
+MINI  — tiny local artifact, instant preview, seconds
+        → agentsam mini (see docs/MINI.md)
+        → intentionally tiny utility lane — not architectural proof
+
+APP   — complete packaged product (npm install / agentsam app add), minutes
+        → Clack catalog: Preview · Info · Doctor · Scaffold/Add · Deploy
+        → maturity-gated actions
+
+WORLD — arbitrary repo/path → deterministic world-state → progressive normalize
+        → agentsam inspect [path]
+        → Merkle + snapshot + AST + brand + harvest + verify + next
+```
+
+---
+
+## Maturity ladder (calculated, observable)
+
+Imperfection is maturity state, not exclusion. Prefer calculated facts over hand labels.
+
+```text
+harvested → scaffolded → wired → verified → releasable → production
+```
+
+| Stage | Gate examples (facts, not badges) |
+|-------|-----------------------------------|
+| harvested | dir exists; optional gallery/canonical paths |
+| scaffolded | package.json / wrangler / preview root present |
+| wired | bin + commands.preview/doctor resolve |
+| verified | doctor + app contract / boundary checks pass |
+| releasable | verify receipts green; no donor junk in publish set; secrets marked |
+| production | deploy receipt / remote binding evidence |
+
+---
+
+## Decision primitives (AgentSam-owned)
+
+**Not** TypeSafe/Jev product vocabulary. Native choose / score / check live under `src/sam/decision/` (see `docs/architecture/SAM_DECISION_WORK_RECEIPT.md`).
+
+| Primitive | Role |
+|-----------|------|
+| predicate / check | yes/no with support |
+| choice | discrete option |
+| score | ordered magnitude (raw estimate unless calibrated) |
+| distribution | deferred / optional |
+
+**Confidence ≠ risk.** Confidence answers “how sure are we?” Risk answers “how bad if wrong?” Abstention and hierarchical degrade are policy, not UI chrome.
+
+Decision receipts (target shape): `{ input_hash, primitive, result, confidence, risk?, next }` — protocol under `protocol/sam/decision-receipt.v1.schema.json`.
+
+First acceptance path: ≥1 classification (e.g. maturity gate or brand route) emits a receipt **without** a model.
+
+---
+
+## World-state
+
+Converge existing slices into one inspectable envelope (extend `repository.snapshot` or add `world.state`):
+
+- files / hashes / MIME (snapshot + merkle)
+- AST / routes / APIs
+- brand packet (when present)
+- app manifest + provenance
+- verify receipts
+- maturity + next_actions
+
+`agentsam inspect` must work for arbitrary paths **and** every `apps/*`.
+
+Consumers: Brand Intelligence, apps catalog, local gallery, progression next-actions. LLM is one handler inside AgentSam — only on ambiguity.
+
+---
+
+## Explicit non-goals
+
+- Repo redesign for package purity
+- New toy/demo apps as architectural proof
+- Requiring finished status before inclusion
+- TypeSafe/Jev dependency or product vocabulary
+- Mini as showcase / poster framing
+- Auto-fetch remotes / auto-delete orphans / execute imported HTML
+- Jump every path to Level-4 LLM
+
+---
+
+## Acceptance (machine-first, without a model)
+
+1. List every `apps/*` with calculated maturity + provenance + verify status  
+2. `agentsam inspect` a harvested site and a serious app → world-state  
+3. Answer what / where / contents / capabilities / reusable / missing / verified / next from receipts  
+4. Expose decision primitives + a confidence-policy receipt on ≥1 classification path  
+5. Keep `agentsam mini` working as the tiny lane  
+6. Docs state this ladder + MINI / APP / WORLD (this file)
+
+---
+
+## Related docs
+
+| Doc | Role |
+|-----|------|
+| `docs/plans/UNIVERSAL-INGEST-MACHINE-FIRST-2026-09-24.md` | Locked work order (Batches A–D) |
+| `docs/plans/MACHINE-FIRST-APPS-TUI-2026-09-24.md` | Apps Clack catalog + batch detail |
+| `docs/plans/TOMORROW-MACHINE-FIRST-BRIEFING.md` | Review index for next session |
+| `docs/MINI.md` | Mini lane |
+| `docs/architecture/SAM_DECISION_WORK_RECEIPT.md` | Decision layer ship receipt |
+| `docs/BRAND_INTELLIGENCE.md` | Consumer of world-state |
+| `docs/REPOSITORY_INTELLIGENCE.md` | Snapshot / inspect substrate |
+| `docs/THEME_REFINERY.md` | Harvest ladder + sites |
+| `protocol/INSPECT_VIEWS_V1.md` | Inspect views |
+| `docs/plans/AGENTSAM-INTERACTIVE-UI-REQUIREMENTS.md` | **Canonical** interactive shell contract (`ctrl-c`) |
+| `docs/plans/AGENTSAM-INTERACTIVE-UI-REQUIREMENTS-codex-tui-20260919.md` | Observational Codex brief (`esc`) — not the implemented contract |

package/docs/WINDOWS_RUNTIME_INSTALL.md

@@ -0,0 +1,30 @@
+# Windows — agentsamd install (Connor / PowerShell)
+
+## Why `Unknown command: runtime` happens
+
+You are on an **old published CLI** (e.g. Agent Sam **v2.6.3**). That build lists `runtime` as a help *topic* but does **not** register the `agentsam runtime` command.
+
+Sam’s Mac works because the global `agentsam` is **`npm link`’d** to the local `agentsam-sdk` checkout (has `runtime` + Windows Scheduled Task).
+
+## Fix (PowerShell)
+
+```powershell
+npm install -g @inneranimalmedia/agentsam-sdk@latest
+agentsam --version
+# need 2.6.5+ (or whatever release includes `runtime`)
+
+agentsam runtime install --yes
+agentsam runtime probe
+# expect healthy on http://127.0.0.1:18765/health
+```
+
+Installs:
+
+- `%USERPROFILE%\.agentsam\bin\agentsamd.exe`
+- Scheduled Task `InnerAnimalMedia\agentsamd` (logon)
+
+Requires **Go** on PATH to build the daemon (`go version`).
+
+## Do not use hosted Studio as the “install”
+
+The Local Studio **desktop app** must load the **bundled** `apps/local-studio` UI from inside the `.app` / `.msi` — not redirect to https://agentsam.inneranimalmedia.com/agentsam. That URL is the cloud Worker surface; the download exists so the product runs offline with agentsamd.

package/docs/architecture/AGENTSAM_APPLICATION_CONTRACT.md

@@ -0,0 +1,188 @@
+# AgentSam Application Contract
+
+**Status:** binding for portable product apps  
+**Schema:** `protocol/apps/agentsam.app.v1.schema.json`  
+**CLI:** `agentsam app validate` · `agentsam app list` · `agentsam app inspect <id>`
+
+## Artifact taxonomy
+
+| Type | Meaning | Canonical manifest |
+|------|---------|-------------------|
+| **APP** | Something a user can install/run/use as a product | `agentsam.app.json` |
+| **PACKAGE** | Reusable code/capability | `agentsam.package.json` (or package metadata) |
+| **SERVICE** | Runtime infrastructure/backend | `agentsam.package.json` with `type: "service"` (or `agentsam.service.json`) |
+| **HOST** | Something that mounts/composes apps | host / install state under `.agentsam/` |
+| **THEME** | Appearance/content kit, not an app | theme package / theme-site scaffold |
+
+A folder under `apps/` is **not** an APP merely because of its path. The AgentSam APP contract (`agentsam.app.json`) makes it one.
+
+Example: `apps/agentsam-go-worker` correctly uses `agentsam.package.json` (`type: "service"`) and must **not** be forced into APP semantics because it is deployable.
+
+Theme packages and static theme-site scaffolds likewise stay outside APP semantics.
+
+## Target tree (conceptual)
+
+```
+apps/
+  cad-creator/
+  client-cms-editor/
+  ecommerce-cms/
+  local-studio/
+
+packages/
+  database-editor/
+  settings/
+  identity/
+  planner/
+  cms-sections/
+  themes/
+
+services/
+  go-runtime/
+  render-runtime/
+```
+
+## Identity namespaces (must not collapse)
+
+| Namespace | Example | Role |
+|-----------|---------|------|
+| `APP.id` | `cad-creator` | Canonical product identity — immutable kebab-case |
+| `HOST.id` / origin | host-install projection | Where this APP instance is served; belongs to installation state, not portable APP identity |
+| npm package | `@inneranimalmedia/agentsam-cad-creator` | Distribute/install code |
+| CLI command | `agentsam-cad-creator` / `agentsam cad` | Launch surface |
+| Cloudflare Worker | `agentsam-cad-creator` | Host deployment name |
+| desktop bundle | `com.inneranimalmedia.agentsam.cadcreator` | OS identity |
+| route | `/cad` | URL mount |
+| service | `cad-render-service` | Infrastructure |
+| `PRODUCT.id` | `cms` | Platform product registry |
+| `MOUNT.id` | `cms-studio` | Host mount slot |
+| remote identity/account issuer | optional host/provider adapter configuration | External account authority for an installation — **not** intrinsic APP identity |
+
+Portable APP law: an installable APP must not hardcode a donor/company hostname, remote issuer, tenant, confidential OAuth client, or customer deployment as a prerequisite for its local product experience. Those facts belong to `agentsam.host-install.v1` state or an explicitly installed provider/identity adapter.
+
+Those names **may** differ. What must not happen:
+
+```js
+const APP = "agentsam-cad-creator"; // Worker name ≠ APP identity
+```
+
+```js
+// Forbidden: collapsing HOST and PLATFORM into alias env vars
+const origin = env.AGENTSAM_STUDIO_ORIGIN || env.AGENTSAM_LOCAL_STUDIO_ORIGIN || env.IAM_OAUTH_ISSUER;
+```
+
+Relate namespaces explicitly:
+
+```json
+{
+  "schema": "agentsam.host-install.v1",
+  "app_id": "local-studio",
+  "config": {
+    "hosts": [
+      { "host_id": "studio-public", "origin": "https://studio.example.com", "role": "production" }
+    ],
+    "identity": { "portable_default": "local" }
+  }
+}
+```
+
+```json
+{
+  "id": "client-cms-editor",
+  "product_id": "cms",
+  "name": "AgentSam CMS",
+  "package": "@inneranimalmedia/client-cms-editor"
+}
+```
+
+```json
+{
+  "schema": "agentsam.host-install.v1",
+  "app_id": "client-cms-editor",
+  "config": {},
+  "mounts": []
+}
+```
+
+## Manifest authority
+
+```
+apps/<app-id>/
+├── agentsam.app.json    ← ONE canonical product definition
+├── package.json
+├── frontend/
+├── backend/
+├── bin/
+└── .agentsam/           ← host / install / project state (not a second product def)
+    └── app.json         ← references app_id; does not redefine identity
+```
+
+| File | Role |
+|------|------|
+| `agentsam.app.json` | Package/product definition — sole APP identity authority |
+| `.agentsam/` | Host/user/project **installation** state for this checkout or customer |
+
+Same APP installed into Fuel & Free Time, Companions CPAs, InnerAnimalMedia, or a customer localhost keeps the same `APP.id`. `.agentsam/` describes **this** installation.
+
+## Physical shape
+
+```
+apps/<app-id>/
+├── agentsam.app.json
+├── package.json
+├── frontend/     # portable presentation/UI
+├── backend/      # application-owned server/runtime
+├── bin/          # launch/install/dev CLI
+├── scripts/
+├── test/
+└── README.md
+```
+
+Not every directory is required for every runtime. Directory **meaning** must not change.
+
+## Runtime identity loading
+
+```js
+import appManifest from "../../agentsam.app.json";
+
+export const APP = Object.freeze(appManifest);
+// APP.id === "cad-creator"
+```
+
+Forbidden:
+
+- `const APP = "..."` (string used as product identity)
+- Duplicated app definitions (root manifest + `.agentsam/app.json` both defining the product)
+- Treating Worker name, npm package name, or route slug as `APP.id`
+
+## AGENTSAM APPLICATION CONTRACT (rules)
+
+APP represents a portable user-facing AgentSam application.
+
+Every APP MUST:
+
+1. Own exactly one canonical `agentsam.app.json`.
+2. Have one immutable kebab-case `APP.id`.
+3. Load runtime APP identity from that manifest.
+4. Keep package, service, Worker, host, route, and desktop identities separate from `APP.id`.
+5. Use explicit `app_id` / `product_id` / `service_id` / `package_id` relationships rather than aliases.
+6. Follow the standard `frontend` / `backend` / `bin` layout.
+7. Declare capabilities and entrypoints in its manifest.
+8. Be runnable independently.
+9. Be discoverable/composable by an AgentSam host.
+10. Pass `agentsam app validate`.
+
+## Resulting composition model
+
+```
+npm / install / package
+          ↓
+      AgentSam APP
+          ↓
+ ┌────────┼─────────┐
+ ▼        ▼         ▼
+standalone Local   another
+app        Studio  APP / host
+```
+
+Goal is **not** one identifier everywhere. Goal is **one canonical identifier per namespace**, with explicit relationships between namespaces.