← All cards

Writing & talks

A performance note from the Connectome Studio migration

A history-preserving, test-led migration from one website to a multi-project tool

I built this website systematically with Jekyll because its file-backed model works well with local AI. Markdown, YAML, Liquid, and Git give both me and an agent something inspectable to work with. Jekyll then turns those canonical files into a static website that does not depend on the editorial application at runtime.

As the site grew into a connectome of focused Cards and explained relationships, I wanted more editorial control than an IDE provided. The local Content Studio emerged as a visual layer over the same files: search, writing, rendered previews, relationship management, diffs, proposals, private conversations, and deliberately invoked AI assistance.

The next requirement is to manage more than one website. I want to use the same Studio with another person’s résumé and source material while giving their project its own content, template, domain, Cloudflare Worker, private state, and Git history.

This card describes how current AI assistance is being used to carry out that migration.

A systematic codebase gives AI a workable surface

The website and Studio had been developed with explicit boundaries, architecture records, tests, and repeatable builds. Those gave the assistant a clear environment to work in:

  1. Read the specification and architectural history.
  2. Inspect the implementation rather than relying on assumptions.
  3. Identify the boundary that needs to change.
  4. Record the architectural decision.
  5. Establish a passing baseline.
  6. Make the change in reversible stages.
  7. Test the old and new boundaries independently.
  8. Remove the old path only after the replacement works.

Current AI technology can work through that environment efficiently. The assistant could keep the intended architecture, implementation details, Git history, tests, filesystem boundaries, and migration sequence in view at the same time. It could move between design discussion and concrete repository evidence without reducing the work to a blind bulk rewrite.

First, the assistant mapped the coupling

The Studio originally lived inside rezarosli.com and assumed that the repository containing the application was also the website it edited.

The assistant searched the code for assumptions involving:

process.cwd
projectRoot
www
_site
.content-studio
build.sh
wrangler

This produced a practical dependency map. Changing CONTENT_ROOT alone would not be sufficient. The content repository could point elsewhere while other services continued to use the original website:

  • preview builds invoked RezaRosli-specific scripts;
  • generated output went to the original private directory;
  • filesystem watchers were created around the original content tree;
  • model-management commands assumed the original www directory;
  • the MCP evidence server located itself relative to the embedded Studio;
  • prompts and tool names contained rezarosli;
  • deployment used one Wrangler configuration.

This is where AI assistance was especially valuable. The assistant could trace one architectural concern across server startup, build orchestration, inference, private storage, command-line tools, tests, and the browser interface. The output was not merely a recommendation to “make paths configurable.” It showed which services had to move together.

Then it converted the idea into an explicit project contract

The reusable system is Connectome Studio. Each website becomes an independent project consumed by it.

The assistant helped define a small committed manifest for each website:

schema_version: 1
id: example-person
name: Example Person
primary_hostname: example.com

content_root: www

jekyll:
  source: www
  production_output: _site
  config:
    - www/_config.yml

deployment:
  provider: cloudflare-workers
  wrangler_config: wrangler.jsonc

The website repository owns its content, templates, assets, effective configuration, hostname, output, and deployment. Connectome Studio owns the reusable editorial behaviour: Cards, Pages, relationships, evidence, lifecycle, proposals, search, graph operations, and AI tools.

The local installation registry needs to know only which project paths are available. Settings, model approvals, private conversations, proposals, histories, audit records, previews, caches, and secrets remain isolated under each project’s .content-studio/ directory.

It checked the latest code before moving it

The most recent work added conversational editor agents and a registry that tests whether a local model can support the behaviours the editor needs.

Rather than assuming the latest commit was a safe extraction point, the assistant compared the code with its accepted architecture decision and roadmap entry. It found that the implementation built successfully but still lacked focused tests around some of the new boundaries.

It added coverage for:

  • private conversation persistence;
  • isolation between project roots;
  • route and body identity mismatches;
  • approved-model enforcement;
  • supported reasoning modes;
  • stale model detection;
  • stale document revisions; and
  • separation between conversational speech and editable artifacts.

It then ran the complete TypeScript check, unit suite, production interface build, and API contract.

The assistant also ran a live compatibility benchmark against gpt-oss:20b. The model passed native streaming, structured output, repository and synthetic-web tool calls, multi-turn correction, cancellation, and recovery checks.

That gave the migration a verified checkpoint rather than an arbitrary snapshot.

It preserved the development history

Connectome Studio has useful history inside the website repository. Copying the current files into an empty repository would preserve the code but lose much of the context for how it developed.

The assistant used Git subtree history to separate the Studio:

git subtree split --prefix=studio

This produced a branch whose commits follow the development of the studio/ directory. The branch was cloned into a temporary workspace where the independent application can be refactored and tested.

The original embedded Studio remains intact while this happens. The migration sequence is deliberately reversible:

Verify the current Studio
        ↓
Create a tested checkpoint
        ↓
Extract its Git history
        ↓
Refactor in a temporary repository
        ↓
Register rezarosli.com as an external project
        ↓
Verify both repositories
        ↓
Remove the embedded copy

Deletion is the final step, not the opening move.

It treated switching as a lifecycle problem

An in-application project selector looks like a small interface feature. The assistant identified it as a concurrency and isolation boundary.

If an AI request begins in Project A and finishes after the user switches to Project B, the response still belongs to Project A. The same applies to saves, previews, model benchmarks, filesystem events, and deployments.

The implementation is therefore moving toward a disposable project service container. Selecting a project creates its content repository, settings, inference services, proposals, model registry, conversations, audits, build service, and filesystem watcher together.

Switching projects must:

  • resolve unsaved documents and conversations;
  • refuse to switch during builds, deployments, benchmarks, or inference;
  • dispose the previous watcher and services;
  • clear browser selection and cached results;
  • identify the project on scoped requests; and
  • reject late requests from the previous project.

This is another example of the value of AI at the migration stage. It can follow the lifetime of an operation through the interface, HTTP API, service container, filesystem, and model runtime, then turn that analysis into tests.

It kept deployment project-owned

Each website has its own Cloudflare Worker and hostname. The Studio may orchestrate deployment, but it must not blur those targets together.

The planned deployment boundary requires:

  1. a current successful preview;
  2. no unsaved document or conversation;
  3. the active project’s Wrangler configuration;
  4. the exact target hostname typed manually; and
  5. a fresh production build and validation before deployment.

The assistant will use Wrangler’s existing authentication rather than copying credentials into Studio. Automated verification uses dry runs; a real deployment remains a separate publishing decision.

It also separated architectural authority

Moving code into another repository is only part of the work. The architectural decisions also need clear ownership.

Website-specific decisions remain with rezarosli.com: its templates, public graph presentation, generated artwork, Jekyll content homes, and deployment behaviour.

Reusable decisions move with Connectome Studio: proposal boundaries, inference providers, model validation, private audits, conversations, lifecycle concepts, and project isolation.

Where a decision crosses the boundary, the Studio owns the general contract and each website owns its implementation. Studio can define what publication status means; a Jekyll project defines how that status affects its pages, feeds, graph, search output, and build.

The assistant classified the existing architecture records so that each decision keeps one canonical owner instead of becoming two editable copies that slowly diverge.

Why AI assistance is useful here

The migration was already structured by the codebase: its boundaries, architecture records, tests, and repeatable builds. The useful change is that current AI technology can work across those layers in one continuous collaboration.

It can read architectural records and then find the exact lines where the implementation diverges. It can identify a missing test, add it, run the suite, inspect the failure, and adjust the design. It can preserve the migration narrative while working through filesystem paths, process lifetimes, model tools, build output, and Cloudflare configuration.

At this stage of a project, that is useful in a very practical way.

The assistant can trace dependencies, make bounded changes, run checks, and preserve evidence across a repository-scale migration. That makes AI useful for changing an existing system, not only generating isolated features.

A note from the assistant: temporary work and performance

From my side, this migration was a sequence of short-lived processes rather than one continuous operation. I read the repository, made a bounded change, started a check, waited for its result, and used that result to decide what to inspect next.

Some of the work used the operating system’s temporary directory. Codex runs created temporary directories under /tmp for schemas, model catalogues, and last-message output. Web retrieval created separate temporary directories for bounded search and fetched-page files. Test fixtures and some tooling used the same OS scratch space.

Those files are different from project state. They are not Git content, not website output, and not the private .content-studio records that persist between runs. The code removes its temporary directories in cleanup blocks, while private audit records deliberately omit temporary paths and credentials.

The distinction has practical implications. Temporary model output can contain unpublished material while a process is running, so directory permissions and process isolation matter. A forced termination can leave scratch files behind, so cleanup cannot be treated as guaranteed. The temporary directory also has finite disk space and is shared with other local work. Project names, prompts, secrets, and generated output should not be placed in predictable filenames there.

The timing showed several different kinds of work. A Jekyll build and link validation were relatively short once the process started. The card-graph regression suite took longer because it built isolated site fixtures repeatedly. The live gpt-oss:20b benchmark took about seventeen seconds and included several model calls; native streaming and structured-output checks accounted for most of that time. Model inference, repository builds, and deployment therefore need different status, cancellation, and timeout handling.

For a multi-project Studio, this temporary work must remain associated with the active project even though the files live outside the project repository. The working directory, MCP project root, audit context, and cleanup ownership all need to travel together. That is part of the performance story: avoiding unnecessary work matters, but knowing exactly which project a process belongs to matters more.

Immediate connections

Explore the cards directly connected to this one.

Connected cards

Follow links in either direction, or find cards that mention this one.

Show