Assisted migration

SEIF Migration turns one existing application into a new, file-native SEIF Context Project. It starts with a local, read-only inventory and a reviewed plan. It does not run the application, install packages, execute hooks, copy source code, copy credentials, or alter the original application.

Journey

Discover one user-authorized application folder. The scanner follows no symlinks and skips .git, .seif, node_modules, generated output, sensitive filenames, special files, binary files, over-large files, and credential-bearing text.
Clarify the first capability, its user or actor, permitted context, tenant and audience boundary, context tests, and integration owner.
Plan a deterministic seif.migration-plan.v1 proposal. Its digest binds the sanitized input inventory and selected HTTP/MCP path.
Review the exclusions, risks, unanswered questions, generated SEIF files, and destination. A plan does not create any files.
Apply only to a new empty folder outside the source application, with the reviewed digest and explicit approval. The source application is never changed.
Integrate manually in the legacy repository after its own code review and test process. The generated project includes an integration review, not an automatic source patch.

# metadata-only, local scan
seif migration scan /path/to/application

# read-only proposal
seif migration plan /path/to/application --integration recommend

# only after reviewing the exact plan digest
seif migration apply /path/to/application \
  --target /path/to/new-seif-project \
  --plan sha256:... --approved

The dedicated local MCP server is separate from the Context MCP server:

seif migration mcp

It exposes migration_scan, migration_plan, migration_render, and migration_apply. The apply tool requires approved: true, the exact planDigest, a new empty destination, and source/destination paths that do not overlap. Migration tools are intentionally absent from hosted project MCP endpoints.

HTTP or MCP

Path	Appropriate when	What SEIF observes	What it cannot prove
HTTP	The legacy application owns a request/turn gateway and can call `seif.http-turn.v1`	Server-issued turn, delivered context, gateway completion or reported failure	Model comprehension, arbitrary tool execution, generated final output, or user receipt
MCP	The application or agent runtime can register a profile-bound context server and manage caller tokens	Context-tool calls recorded by the SEIF MCP server	Work outside those calls, model reasoning, output delivery, or token use by another runtime
Neither yet	The capability boundary, authorized content, or runtime owner is not ready	No runtime telemetry	Anything about production behavior

The migration plan recommends HTTP only when it sees an HTTP server or route definition. A user can select MCP or HTTP anyway, but the plan records an integration-fit warning when the corresponding surface was not detected.

What a generated project contains

The generated folder has seif.yaml, one empty consumer/profile, a safe objective, a metadata-only inventory, migration questions, an integration review, and the immutable reviewed plan under migration/. It deliberately starts with no copied business facts. Add only owner-reviewed, authorized materials and then define Context Tests.

The generated AGENTS.md is a provider-neutral pointer. It names the plan and migration MCP workflow, but never authorizes an agent to access the old repository, customer data, tenant data, secrets, or production systems.

Boundaries and evidence

A migration plan is canonical structured evidence for that conversion. It records source digest, scan policy, skipped entries, risks, selected integration path, proposed generated artifacts, and explicit unanswered questions. The optional vector index is derived retrieval only. It is not an authorization record, source of truth, or substitute for reviewing the plan.

Plans expire naturally when the sanitized source inventory changes. Apply recomputes the plan and rejects a stale digest. A non-empty destination, source/destination overlap, malformed plan, or missing approval is refused without modifying the source application.

Optional documentation index

docs/migration.md is canonical migration documentation. The searchable corpus, however, is the whole docs/ tree: seif migration docs (and the diagnostic panel in the web Contexto screen) searches every Markdown file under docs/, so a question about the Compass, profiles, the suite or going live finds the right page, not only the migration guide. Searching works lexically without network access; a separately configured Qdrant index speeds semantic retrieval when an embedding endpoint is available.

Variable	Meaning
`SEIF_MIGRATION_QDRANT_URL`	Qdrant base URL. Localhost HTTP is allowed; remote endpoints must use HTTPS.
`SEIF_MIGRATION_QDRANT_COLLECTION`	Optional collection name. Default: `seif-migration-docs`.
`SEIF_MIGRATION_QDRANT_API_KEY`	Optional Qdrant key. Read only from the environment and never written or displayed.
`SEIF_MIGRATION_EMBEDDINGS_URL`	OpenAI-compatible `/v1/embeddings` endpoint.
`SEIF_MIGRATION_EMBEDDINGS_MODEL`	Embedding model name.
`SEIF_MIGRATION_EMBEDDINGS_API_KEY`	Optional embedding service key. Read only from the environment.
`SEIF_MIGRATION_ALLOW_HTTP`	Set only to `1` for a trusted private embeddings endpoint such as an operator-managed tailnet Ollama. Public endpoints still should use HTTPS.

Use seif migration docs status to inspect configuration and reachability. seif migration docs index --approved is explicit and idempotent: it creates the named collection only when absent, then upserts content-hashed chunks of every doc. It never deletes a collection or its points. The index is derived: when the docs change, re-run index --approved to refresh semantic retrieval (the manifest digest changes); lexical search reflects the change at once. Qdrant search needs both Qdrant and an embedding endpoint; if either is absent or unavailable, search returns canonical lexical results with a typed remote status.

Never place API keys in project files, migration plans, pointer documents, command arguments, logs, or screenshots.