Moving a shared piece is not a path change

On June 8 there were several commits that look small when read in isolation:

10:48 - docs: move nima agent to packages
10:48 - system: load nima agent from packages
10:48 - editor: package nima agent from packages
17:02 - docs: add workspace setup migration guide
17:02 - app: restructure reveal it frontend

The quick reading is "a shared module moved and the docs were updated".

The correct reading is different: a piece is only truly shared when the whole workspace knows how to live with it.

The small change that was not small

nima-agent should no longer live as a component hanging off one product. The morning change moved it into packages, and made both nima-system and nima-editor load it from there.

That was not folder aesthetics. It was an ownership correction.

If several products consume a capability, its address should also communicate who owns it:

flowchart LR component["Component tied\nto one product"] --> package["Shared package"] package --> editor["nima-editor"] package --> system["nima-system"] package --> docs["Documentation"] package --> setup["Workspace bootstrap"]

As long as shared code still lives under one product, the code may be reusable, but the architecture is still lying.

What the commit forced us to touch

Moving nima-agent to packages did not end at the imports.

Four layers had to realign:

Layer	What changed	Why it mattered
Consumers	`nima-system` and `nima-editor` now load the agent from `packages`	It stops one product from looking like the owner of a shared capability
Documentation	README and architecture maps point at the new location	The official structure stops contradicting the code
Bootstrap	a workspace migration guide and setup script were added	A reorganized repo that cannot be rebuilt easily is an incomplete reorganization
Operations	the state of dozens of repos had to be reviewed before updating	Changing workspace topology forces stricter operational discipline

The third point matters most. Once you need a migration guide and a setup script, you are no longer tidying folders. You are changing the project's onboarding contract.

The chat that made the rule obvious

That same day there was an operational chat about syncing all repos in the local workspace.

What mattered was not the git pull. It was the sequence of thought:

First came a bulk fetch and review.
The root repo was found to have local changes, while the remote also touched README.md.
Work stopped before crossing the destructive boundary.
The local changes were then compared against the new reorganization.
Only after that were obsolete local edits discarded.
Finally, the scope itself was widened, because the first pass counted 20 repos while the real local workspace had 22.

That chat explained a platform rule better than the code did: never update a reorganized workspace as if it were one big folder; update it as a system with scope, ownership and risk.

Why the migration guide was product work

The afternoon commit added a workspace migration guide and a setup-notipad-workspace.ps1 script.

That can look like internal documentation, but it is actually platform product work.

When a platform still depends on one person remembering:

which repo belongs where,
which folder is no longer canonical,
which consumer loads from which package,
and which script must run after the change,

the platform does not fully exist yet. What exists is operator memory.

The guide turns memory into procedure. The script turns procedure into repeatable startup.

The good side effect: products can be restructured without re-owning shared code

Hours later, reveal-it-app went through a large frontend restructure: routes, partials, SEO content, shared shell, assets and scripts.

It is not the same change, but it shows the same lesson.

The clearer shared ownership becomes, and the easier the workspace is to rebuild, the easier it is for a product repo to change deeply without mixing boundaries again.

The goal was not "have a packages folder". The goal was to move large pieces without hiding dependencies inside the wrong product again.

What I am taking from this stretch

Shared does not mean "used by several"; it means "placed, documented and loaded as shared".
A reorganization is not done when it compiles; it is done when another workspace can boot without tribal knowledge.
Operational chats are architecture too. Sometimes they reveal risk more clearly than diagrams do.
Reviewing scope before deleting is technical discipline, not administrative caution.

Moving a shared piece was not a git mv. It was an ownership correction, followed by a bootstrap correction and an operations correction.

That is a useful signal: when a path change forces code, docs, setup and sync criteria to move together, you are not moving a file. You are stabilizing a platform.

Part of my platform notes. Follow the blog or contact me.