everything-dev 2.0.0-rc.8 → 2.0.0-rc.9

package/dist/version-manifest-resolve.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"version-manifest-resolve.mjs","names":[],"sources":["../src/version-manifest-resolve.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport { existsSync, readdirSync, readFileSync, statSync } from \"node:fs\";\nimport path from \"node:path\";\nimport {\n  type WorkspaceVersionManifest,\n  WorkspaceVersionManifestSchema,\n} from \"every-plugin/version-manifest\";\nimport { bundleUrlToStagedPath, resolveContained } from \"./resolver\";\n\n/**\n * Version-manifest slot resolution (atomic-deploys 04): a config slot's\n * `pin` ({ manifest, integrity }) resolves to the derived entry-level fields\n * every consumer needs. The cache is keyed by the full pin — the pinned\n * bytes are immutable, so a verified entry is cached for the process\n * lifetime and serves as last-known-good if the origin later fails; a fetch\n * or SRI failure with nothing cached propagates (a boot-time resolution\n * failure fails the deploy, which is the platform's rollback).\n */\n\nexport interface ResolvedSlotVersion {\n  /** Absolute URL of the content-hashed container entry. */\n  entryUrl: string;\n  entryIntegrity: string;\n  /** Absolute URL of the hashed browser manifest (mf-manifest), when present. */\n  browserManifestUrl?: string;\n  /** Absolute URL of the content-hashed SSR entry, when present. */\n  ssrEntryUrl?: string;\n  ssrIntegrity?: string;\n  /** Full per-file digest map of the dist (object path → SRI), when the\n   * pinned manifest carries one — the diff base for skip-unchanged uploads. */\n  files?: Record<string, string>;\n}\n\nexport interface SlotPin {\n  /** versioned manifest filename, relative to the slot's production base */\n  manifest: string;\n  /** the manifest document's own SRI */\n  integrity: string;\n}\n\nconst cache = new Map<string, ResolvedSlotVersion>();\n\nexport function clearSlotVersionCache(): void {\n  cache.clear();\n}\n\nfunction fetchText(url: string, fetchImpl: typeof fetch): Promise<string> {\n  return fetchImpl(url).then((response) => {\n    if (!response.ok) throw new Error(`version manifest fetch failed: ${response.status}`);\n    return response.text();\n  });\n}\n\nfunction slotVersionFromManifest(\n  base: string,\n  manifest: WorkspaceVersionManifest,\n): ResolvedSlotVersion {\n  const trimmedBase = base.replace(/\\/$/, \"\");\n  return {\n    entryUrl: `${trimmedBase}/${manifest.entry}`,\n    entryIntegrity: manifest.entryIntegrity,\n    ...(manifest.browserManifest\n      ? { browserManifestUrl: `${trimmedBase}/${manifest.browserManifest.file}` }\n      : {}),\n    ...(manifest.ssr\n      ? {\n          ssrEntryUrl: `${trimmedBase}/${manifest.ssr.entry}`,\n          ssrIntegrity: manifest.ssr.integrity,\n        }\n      : {}),\n    ...(manifest.files ? { files: manifest.files } : {}),\n  };\n}\n\n/**\n * Staged-slot preference (ADR 0020/0021 self-contained tier): when a runtime\n * stages its own namespace under `BOS_BUNDLE_DIR`, a slot resolves from the\n * staged dist's own version manifest instead of the config's pin — pinned\n * manifest bytes that predate the image (deploy lag after a release bump)\n * cannot exist in the staged namespace, so their hashed files would 404 the\n * disk and fall through to the network, where the stale immutable bytes\n * still answer 200 and boot a foreign build. The staged manifest is trusted\n * (staged by the image build itself) and skipped entirely when the slot is\n * absent from the staged namespace or the pinned manifest is present (the\n * normal healthy case, which keeps the pin's SRI check).\n */\nfunction readStagedSlotVersion(base: string, pin: SlotPin): ResolvedSlotVersion | null {\n  const bundleDir = process.env.BOS_BUNDLE_DIR;\n  if (!bundleDir) return null;\n\n  const slotDir = bundleUrlToStagedPath(base, bundleDir);\n  if (!slotDir || !existsSync(slotDir)) return null;\n\n  const pinnedManifestPath = resolveContained(slotDir, pin.manifest);\n  if (!pinnedManifestPath || existsSync(pinnedManifestPath)) return null;\n\n  const versionsDir = path.join(slotDir, \"versions\");\n  if (!existsSync(versionsDir)) return null;\n  const manifests = readdirSync(versionsDir)\n    .filter((name) => name.endsWith(\".json\"))\n    .map((name) => path.join(versionsDir, name))\n    .filter((file) => statSync(file).isFile())\n    .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs || (a < b ? -1 : 1));\n  if (manifests.length === 0) return null;\n  const manifestPath = manifests[0];\n  if (!manifestPath) return null;\n\n  try {\n    const manifest = WorkspaceVersionManifestSchema.parse(\n      JSON.parse(readFileSync(manifestPath, \"utf8\")),\n    );\n    return slotVersionFromManifest(base, manifest);\n  } catch {\n    return null;\n  }\n}\n\nexport async function resolveSlotVersion(input: {\n  base: string;\n  pin: SlotPin;\n  fetchImpl?: typeof fetch;\n}): Promise<ResolvedSlotVersion> {\n  const key = `${input.base}::${input.pin.manifest}::${input.pin.integrity}`;\n  // content-addressed: a verified pin is cached for the process lifetime and\n  // never refetched — the cache IS the last-known-good\n  const cached = cache.get(key);\n  if (cached) return cached;\n\n  const staged = readStagedSlotVersion(input.base, input.pin);\n  if (staged) {\n    cache.set(key, staged);\n    return staged;\n  }\n\n  const manifestUrl = `${input.base.replace(/\\/$/, \"\")}/${input.pin.manifest.replace(/^\\//, \"\")}`;\n  const body = await fetchText(manifestUrl, input.fetchImpl ?? fetch);\n  const computed = `sha384-${createHash(\"sha384\").update(body).digest(\"base64\")}`;\n  if (computed !== input.pin.integrity) {\n    throw new Error(\n      `[SRI] version manifest integrity mismatch for ${manifestUrl}\\n  Expected: ${input.pin.integrity}\\n  Computed: ${computed}`,\n    );\n  }\n  const manifest: WorkspaceVersionManifest = WorkspaceVersionManifestSchema.parse(JSON.parse(body));\n\n  const resolved = slotVersionFromManifest(input.base, manifest);\n  cache.set(key, resolved);\n  return resolved;\n}\n"],"mappings":"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"}
+{"version":3,"file":"version-manifest-resolve.mjs","names":[],"sources":["../src/version-manifest-resolve.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport { existsSync, readdirSync, readFileSync, statSync } from \"node:fs\";\nimport path from \"node:path\";\nimport {\n  type SourceRef,\n  type WorkspaceVersionManifest,\n  WorkspaceVersionManifestSchema,\n} from \"every-plugin/version-manifest\";\nimport { bundleUrlToStagedPath, resolveContained } from \"./resolver\";\n\n/**\n * Version-manifest slot resolution (atomic-deploys 04): a config slot's\n * `pin` ({ manifest, integrity }) resolves to the derived entry-level fields\n * every consumer needs. The cache is keyed by the full pin — the pinned\n * bytes are immutable, so a verified entry is cached for the process\n * lifetime and serves as last-known-good if the origin later fails; a fetch\n * or SRI failure with nothing cached propagates (a boot-time resolution\n * failure fails the deploy, which is the platform's rollback).\n */\n\nexport interface ResolvedSlotVersion {\n  /** Absolute URL of the content-hashed container entry. */\n  entryUrl: string;\n  entryIntegrity: string;\n  /** Absolute URL of the hashed browser manifest (mf-manifest), when present. */\n  browserManifestUrl?: string;\n  /** Absolute URL of the content-hashed SSR entry, when present. */\n  ssrEntryUrl?: string;\n  ssrIntegrity?: string;\n  /** Full per-file digest map of the dist (object path → SRI), when the\n   * pinned manifest carries one — the diff base for skip-unchanged uploads. */\n  files?: Record<string, string>;\n  /** Source archive reference from the pinned manifest (publish.sourcePublish). */\n  source?: SourceRef;\n}\n\nexport interface SlotPin {\n  /** versioned manifest filename, relative to the slot's production base */\n  manifest: string;\n  /** the manifest document's own SRI */\n  integrity: string;\n}\n\nconst cache = new Map<string, ResolvedSlotVersion>();\n\nexport function clearSlotVersionCache(): void {\n  cache.clear();\n}\n\nfunction fetchText(url: string, fetchImpl: typeof fetch): Promise<string> {\n  return fetchImpl(url).then((response) => {\n    if (!response.ok) throw new Error(`version manifest fetch failed: ${response.status}`);\n    return response.text();\n  });\n}\n\nfunction slotVersionFromManifest(\n  base: string,\n  manifest: WorkspaceVersionManifest,\n): ResolvedSlotVersion {\n  const trimmedBase = base.replace(/\\/$/, \"\");\n  return {\n    entryUrl: `${trimmedBase}/${manifest.entry}`,\n    entryIntegrity: manifest.entryIntegrity,\n    ...(manifest.browserManifest\n      ? { browserManifestUrl: `${trimmedBase}/${manifest.browserManifest.file}` }\n      : {}),\n    ...(manifest.ssr\n      ? {\n          ssrEntryUrl: `${trimmedBase}/${manifest.ssr.entry}`,\n          ssrIntegrity: manifest.ssr.integrity,\n        }\n      : {}),\n    ...(manifest.files ? { files: manifest.files } : {}),\n    ...(manifest.source ? { source: manifest.source } : {}),\n  };\n}\n\n/**\n * Staged-slot preference (ADR 0020/0021 self-contained tier): when a runtime\n * stages its own namespace under `BOS_BUNDLE_DIR`, a slot resolves from the\n * staged dist's own version manifest instead of the config's pin — pinned\n * manifest bytes that predate the image (deploy lag after a release bump)\n * cannot exist in the staged namespace, so their hashed files would 404 the\n * disk and fall through to the network, where the stale immutable bytes\n * still answer 200 and boot a foreign build. The staged manifest is trusted\n * (staged by the image build itself) and skipped entirely when the slot is\n * absent from the staged namespace or the pinned manifest is present (the\n * normal healthy case, which keeps the pin's SRI check).\n */\nfunction readStagedSlotVersion(base: string, pin: SlotPin): ResolvedSlotVersion | null {\n  const bundleDir = process.env.BOS_BUNDLE_DIR;\n  if (!bundleDir) return null;\n\n  const slotDir = bundleUrlToStagedPath(base, bundleDir);\n  if (!slotDir || !existsSync(slotDir)) return null;\n\n  const pinnedManifestPath = resolveContained(slotDir, pin.manifest);\n  if (!pinnedManifestPath || existsSync(pinnedManifestPath)) return null;\n\n  const versionsDir = path.join(slotDir, \"versions\");\n  if (!existsSync(versionsDir)) return null;\n  const manifests = readdirSync(versionsDir)\n    .filter((name) => name.endsWith(\".json\"))\n    .map((name) => path.join(versionsDir, name))\n    .filter((file) => statSync(file).isFile())\n    .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs || (a < b ? -1 : 1));\n  if (manifests.length === 0) return null;\n  const manifestPath = manifests[0];\n  if (!manifestPath) return null;\n\n  try {\n    const manifest = WorkspaceVersionManifestSchema.parse(\n      JSON.parse(readFileSync(manifestPath, \"utf8\")),\n    );\n    return slotVersionFromManifest(base, manifest);\n  } catch {\n    return null;\n  }\n}\n\nexport async function resolveSlotVersion(input: {\n  base: string;\n  pin: SlotPin;\n  fetchImpl?: typeof fetch;\n}): Promise<ResolvedSlotVersion> {\n  const key = `${input.base}::${input.pin.manifest}::${input.pin.integrity}`;\n  // content-addressed: a verified pin is cached for the process lifetime and\n  // never refetched — the cache IS the last-known-good\n  const cached = cache.get(key);\n  if (cached) return cached;\n\n  const staged = readStagedSlotVersion(input.base, input.pin);\n  if (staged) {\n    cache.set(key, staged);\n    return staged;\n  }\n\n  const manifestUrl = `${input.base.replace(/\\/$/, \"\")}/${input.pin.manifest.replace(/^\\//, \"\")}`;\n  const body = await fetchText(manifestUrl, input.fetchImpl ?? fetch);\n  const computed = `sha384-${createHash(\"sha384\").update(body).digest(\"base64\")}`;\n  if (computed !== input.pin.integrity) {\n    throw new Error(\n      `[SRI] version manifest integrity mismatch for ${manifestUrl}\\n  Expected: ${input.pin.integrity}\\n  Computed: ${computed}`,\n    );\n  }\n  const manifest: WorkspaceVersionManifest = WorkspaceVersionManifestSchema.parse(JSON.parse(body));\n\n  const resolved = slotVersionFromManifest(input.base, manifest);\n  cache.set(key, resolved);\n  return resolved;\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "everything-dev",
-  "version": "2.0.0-rc.8",
+  "version": "2.0.0-rc.9",
   "type": "module",
   "engines": {
     "node": ">=20.11"
@@ -243,10 +243,11 @@
     "dotenv": "^17.3.1",
     "effect": "4.0.0-rc.117",
     "@everything-dev/upload-app": "workspace:^",
-    "every-plugin": "^3.0.0-rc.5",
+    "every-plugin": "^3.0.0-rc.6",
     "execa": "^9.5.2",
     "glob": "^13.0.6",
     "near-kit": "^0.20.2",
+    "@outlayer/sdk": "0.1.0-alpha.4",
     "pg": "^8.12.0",
     "tar": "^7.4.3",
     "yaml": "2.9.0",

package/skills/cli-reference/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 
 # CLI Command Reference
 
-19 `bos` commands organised by workflow category.
+20 `bos` commands organised by workflow category.
 
 ## Development
 
@@ -119,6 +119,22 @@ bos upgrade --no-sync       # only upgrade packages, skip template sync
 
 → [`init-upgrade`](.) skill for catalog strategy, legacy import rewrites, and upgrade+publish flow.
 
+### `bos import`
+
+Import a workspace subtree (e.g. `plugins/auth`) from an upstream — a GitHub repo, a local directory, a `bos://` published runtime, or (default) the authored config's extends chain. Chain-resolved sources walk outward to the nearest ancestor declaring the workspace; when the ancestor publishes source archives (`publish.sourcePublish`, ADR 0030) the import byte-sources from the pinned, SRI-verified archive (no GitHub needed, `repository` optional) and falls back to the chain's `repository` (pinned to the manifest's git sha, HEAD otherwise) only when no archive exists. Per-file classification is snapshot-baselined; diverging migration chains are reconciled — applied local entries are kept verbatim, colliding upstream migrations are renumbered and appended, journal rebuilt. Unresolvable conflicts (content drift on an applied migration, unreadable journal) hold the chain and gate the run (exit 1) unless `--yes` or an interactive confirmation.
+
+**Flags:** `--from <bos://<account>/<gateway> | owner/repo[@ref] | url | dir>` (optional — extends chain when omitted) `--yes` `--dry-run` `--no-install` `--json`
+
+```bash
+bos import plugins/auth                                    # resolved through the extends chain
+bos import plugins/auth --from bos://base.near/base        # chain of a published runtime
+bos import plugins/auth --from NEARBuilders/everything-dev@v2.1.0
+bos import plugins/auth --from ./local-checkout --dry-run
+bos import plugins/auth --from owner/repo --yes
+```
+
+→ [`init-upgrade`](.) skill for source resolution, classification buckets, migration-chain reconciliation, route deltas, and the `.bos/import-report.md` report.
+
 ### `bos status`
 
 Show project health: package versions, parent reachability, last sync, env file status, and update availability.

package/skills/init-upgrade/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: init-upgrade
-description: bos init, bos sync, and bos upgrade workflows — template download, snapshot-based conflict detection, package version bumps, and how init/sync select and own files. Use when scaffolding new projects, syncing upstream changes, or upgrading framework packages.
+description: bos init, bos sync, bos import, and bos upgrade workflows — template download, snapshot-based conflict detection, workspace import from upstream repos with divergence reporting, package version bumps, and how init/sync select and own files. Use when scaffolding new projects, syncing upstream changes, importing a workspace subtree from another repo, or upgrading framework packages.
 metadata:
-  sources: "packages/everything-dev/src/cli/init.ts,packages/everything-dev/src/cli/sync.ts,packages/everything-dev/src/cli/upgrade.ts,packages/everything-dev/src/cli/snapshot.ts,packages/everything-dev/src/cli.ts,packages/everything-dev/src/merge.ts"
+  sources: "packages/everything-dev/src/cli/init.ts,packages/everything-dev/src/cli/sync.ts,packages/everything-dev/src/cli/import.ts,packages/everything-dev/src/commands/import.ts,packages/everything-dev/src/cli/upgrade.ts,packages/everything-dev/src/cli/snapshot.ts,packages/everything-dev/src/cli.ts,packages/everything-dev/src/merge.ts"
 ---
 
 > **Config form:** the authored config is `bos.app.ts` (canonical, preferred when both exist). A legacy `bos.config.json` is still supported for older children. Where this doc says `bos.config.json` for the *local authored file*, read "the authored config". The published artifact on FastKV keeps the key name `bos.config.json`.
 
-# bos init, sync, upgrade
+# bos init, sync, import, upgrade
 
 ## bos init
 
@@ -182,6 +182,76 @@ bos upgrade --dry-run    # Preview without making changes
 
 Workspace packages use `catalog:` refs so a single version bump in root catalog propagates everywhere. Skips `workspace:*` and `file:` refs.
 
+## bos import
+
+Imports a workspace subtree (e.g. `plugins/auth`) from an upstream GitHub repo or a local directory — no clone of the full history, just a tarball (or direct local read) of one ref. The upstream can also be resolved through the authored config's `extends` chain (a bos:// URL centric source — see below):
+
+```bash
+bos import plugins/auth                          # resolved through the extends chain
+bos import plugins/auth --from bos://base.near/base
+bos import plugins/auth --from NEARBuilders/everything-dev
+bos import plugins/auth --from NEARBuilders/everything-dev@v2.1.0
+bos import plugins/auth --from NEARBuilders/everything-dev@everything-dev@2.0.0-rc.8
+bos import plugins/auth --from https://github.com/owner/repo@develop
+bos import plugins/auth --from ./local-checkout --dry-run
+bos import plugins/auth --from owner/repo --yes
+```
+
+**Flags:** `--from <bos://<account>/<gateway> | owner/repo[@ref] | url | dir>` (optional — resolve through the extends chain when omitted), `--yes`, `--dry-run`, `--no-install`, `--json`. The GitHub ref splits on the **first** `@`, so changesets-style tags keep their own `@`.
+
+### Source resolution
+
+`--from` takes three shapes:
+
+- **`bos://<account>/<gateway>`** — the config published to FastKV by that runtime. The extends chain of that runtime is walked outward to the **nearest ancestor whose own config declares the workspace locally** (`local:<workspace-path>`); the tarball comes from that ancestor's `repository` field (continuing rootward when the declaring runtime itself lacks one).
+- **omitted** — same chain walk, starting from the authored `bos.app.ts` (v2 config only). Errors when the workspace is declared locally in the child (you own it — nothing to import), when no runtime in the chain declares the workspace, or when no ancestor along the chain carries a `repository`.
+- **`<owner/repo>[@ref]`, GitHub URL, or local dir** — explicit source, unchanged.
+
+**Ref pinning:** the ancestor's published config pins each workspace to an immutable version manifest. When the ancestor publishes source archives (`publish.sourcePublish` on its authored config, ADR 0030), the import **byte-sources** from the pinned archive: the manifest itself is SRI-verified against the config slot pin, the archive URL + server SRI come from the manifest's `source` field, the bytes are SRI-verified and extracted (repo-root-relative — a drop-in for the GitHub tarball root), and no GitHub dependency exists (the parent's `repository` may be absent or private). If archive fetch fails or its SRI mismatches, the import falls back to the chain-resolved GitHub coordinate with a `Note:`. When the manifest records no `source`, GitHub remains the source: a recorded `git sha` pins the exact deployed commit; otherwise the import falls back to the **default branch (HEAD)** with a `Note:` line. The report's Source section shows both layers: the `bos:// …` extends ref, the source archive URL when used, and the dereferenced `repository @ ref`.
+
+### Classification
+
+Each file shared between the local workspace and the upstream subtree is classified against a baseline: `.bos/import-snapshot.json` (written by previous imports), falling back to `.bos/sync-snapshot.json`.
+
+| Bucket | Meaning | Action |
+|---|---|---|
+| added | upstream-only | written |
+| unchanged | identical content | nothing (baseline recorded) |
+| updated | local matches baseline, upstream moved | overwritten with upstream (backed up first) |
+| preserved-local | local-only, upstream lacks it | never deleted |
+| preserved-local-edit | upstream matches baseline, local edited | local wins, untouched |
+| merged | diverged `package.json` | structured merge — template wins shared keys, local-only keys and deps preserved |
+| conflict | both changed since baseline, or no baseline exists | gated |
+
+Local-only files are never deleted, even when upstream no longer carries them.
+
+### Gating
+
+Conflicts — and a migration chain that cannot be applied verbatim (next section) — gate the import:
+
+- **Non-TTY without `--yes`:** nothing is written, the report is emitted, exit 1. `--yes` applies upstream over conflicting files (local copies backed up to `.bos/import-backup/<timestamp>/`) and proceeds.
+- **TTY:** an interactive confirm (default No; declining exits 1).
+
+A diverged `package.json` is never a conflict when both sides parse — it merges instead.
+
+### Migration chain reconciliation
+
+When both sides have `src/db/migrations/` journals, the chain is **reconciled** instead of overwritten:
+
+- **Applied entries win.** Every local journal entry is presumed applied to the database and is kept verbatim — never renumbered or rehashed.
+- **Colliding upstream migrations are renumbered and appended.** An upstream entry that shares an idx or lands below the local tail but is not present locally is renumbered after the local tail in upstream order: upstream `0011_team-member-role` with a local tail at idx 12 becomes `0013_team-member-role`. The `.sql` file is copied to the new name, `meta/<idx>_snapshot.json` is renamed to match, and the migration journal under `meta` (`_journal.json`) is rebuilt (local entries verbatim + appended entries carrying upstream's `when`/`version`).
+- **Content matching keeps repeat imports convergent.** An upstream entry whose SQL content hash matches a local entry (e.g. one imported under a renumbered tag earlier) is treated as already imported — nothing is appended twice.
+- **Report.** The import report and console output show the kept set (applied), the appended set (`fromTag → toTag`, new idx), and what the next boot will apply versus what is already applied. Renamed snapshots record upstream intermediate schema states — review `drizzle-kit generate` output against the merged chain before generating new migrations.
+- **Held back.** Only unresolvable drift holds the chain now: a shared tag whose SQL content differs locally (already-applied hashes would drift), or an unreadable journal. Held chain files are not written; the rest of the workspace imports normally. A held chain gates the run even when no other file conflicts.
+
+### Route-set delta
+
+Both sides' contract surface is scanned for literal `.route({ method, path })` pairs — the monolithic `<workspace>/src/contract.ts` plus any split `<workspace>/src/contract/**` files, unioned per side (so a monolithic local contract compares correctly against a re-export + split-file upstream). The report lists ours-only and theirs-only `METHOD path` routes so API drift is visible before you port local routes onto the new upstream contract.
+
+### Report and baselines
+
+Every run — dry-run, refused, or applied — writes `.bos/import-report.md`: summary table, conflict checklist with reasons and held markers, the migration-chain reconciliation plan (kept/appended/held), route delta, bucket lists, and next steps. Written and unchanged files are recorded to `.bos/import-snapshot.json` (and merged into `.bos/sync-snapshot.json` when one exists) so the next import detects drift instead of starting from zero.
+
 ## bos publish
 
 See `everything-dev#publish-sync` for the full publish workflow. A quick reference:
@@ -206,6 +276,8 @@ Unknown keys go after known keys. See `everything-dev#extends-config` for full o
 
 **"Sync reports conflicted files."** Your local edits diverged from the snapshot; upgrade applies the template version and leaves your copy in `.bos/sync-backup/` — diff and merge back, or `bos sync --force` deliberately.
 
+**"Import a workspace from the base platform."** `bos import <workspace> --dry-run` (defaults to the extends chain; or `--from <owner/repo>` for an explicit upstream) first, read `.bos/import-report.md` for the conflict/migration/route picture, then real-run: plain invoke prompts in a TTY, `--yes` applies upstream over conflicts (backed up), and a flagged migration chain stays held until reconciliation.
+
 **"Upgrade framework packages."** `bos upgrade --dry-run` first, then `bos upgrade` — it bumps the root catalog, rewrites workspace refs to `catalog:`, syncs the template, and rewrites legacy imports.
 
 ## What comes back when it refuses
@@ -214,5 +286,6 @@ Unknown keys go after known keys. See `everything-dev#extends-config` for full o
 |---|---|
 | file listed as `conflicted` in sync results | local file modified since the snapshot AND the template changed — take the template version (your copy is backed up at `.bos/sync-backup/`) or re-apply your change on top |
 | sync keeps skipping my file | app-owned files that diverged from the snapshot are skipped without `--force`; framework-owned files always update when the template changes |
+| import exits 1 listing files | unresolvable conflicts (or a held migration chain) — read `.bos/import-report.md`, then re-run with `--yes` to apply upstream (local copies land in `.bos/import-backup/`), or port local changes manually first |
 | `Circular extends detected while resolving upgrade source` | the upgrade source's extends chain loops — resolve from a non-cyclic parent |
 | init copies fewer files than expected | `buildInitPatterns` filters to the selected plugins + their routes; pass `--overrides ui,api,host` to widen the scaffold |