WIP simplifying load/startup

docs/architecture.md

@@ -85,7 +85,7 @@ Only canonical catalog resources are part of the runtime contract in this phase.
 
 ### Registry Loader
 
-The runtime composition includes a startup registry loader that reads packaged docs resources using `importlib.resources.files(...)` and `Traversable` APIs.
+Importing the package does not read or parse documentation. The MCP server and FastAPI application factories request the registry when constructing a runnable server, using packaged resources through `importlib.resources.files(...)` and `Traversable` APIs.
 
 Loader responsibilities:
 
@@ -94,12 +94,16 @@ Loader responsibilities:
 3. Build an in-memory registry keyed by `skill_id`.
 4. Fail fast for duplicate ids, missing markdown files, and broken reference mappings.
 
-Registry load failure is a startup error, not a partial runtime warning.
+The immutable registry is cached for the process lifetime. Each Uvicorn worker constructs and retains its own registry because worker processes do not share Python objects. Registry load failure is a server-factory startup error, not a package-import error or partial runtime warning.
 
 ### Content Sources
 
 Content is authored in markdown under `docs/` and managed as long-form reference material. Skill documents and companion references now live under `docs/skills/`, while project-authored pages remain alongside them in the docs tree. Resource handlers expose the same authored documents through stable resource URIs.
 
+The repository root `docs/` directory is the only authored source. The `src/personal_mcp/docs` path is a relative symlink to that directory for source-checkout and editable-install workflows; it is not a second content tree and packaging does not depend on traversing it.
+
+For wheel builds, [Hatchling forced inclusion](https://hatch.pypa.io/latest/config/build/#forced-inclusion) maps the root `docs/` tree to `personal_mcp/docs/`. The wheel therefore contains regular resource files at that destination rather than a symlink. Runtime registry loading uses [`importlib.resources.files`](https://docs.python.org/3/library/importlib.resources.html#importlib.resources.files) and `Traversable` operations from the `personal_mcp` package anchor, so it does not depend on the repository layout or current working directory.
+
 ### Static Docs Surface
 
 Static docs are built directly from two markdown source streams:
@@ -109,6 +113,8 @@ Static docs are built directly from two markdown source streams:
 
 The merged docs tree is built by Zensical into static files and served by the FastAPI app.
 
+Generated `site/` files are deployment assets for the human-facing static site. They are separate from the authored Markdown resources packaged under `personal_mcp/docs/`.
+
 ## Data Flow
 
 ```mermaid