documentation-engine 0.1.2__tar.gz → 0.2.0__tar.gz

{documentation_engine-0.1.2 → documentation_engine-0.2.0}/.github/workflows/release.yml

@@ -148,6 +148,9 @@ jobs:
         uses: astral-sh/setup-uv@v7
         with:
           python-version: "3.12"
+          # This deliberately checkout-free consumer job has no uv.lock or
+          # pyproject.toml from which setup-uv could derive a cache key.
+          enable-cache: false
 
       - name: Create the consumer environment on Python 3.12
         run: |

{documentation_engine-0.1.2 → documentation_engine-0.2.0}/.gitignore

@@ -8,6 +8,7 @@ __pycache__/
 /.docsystem.toml
 /.docsystem/
 .docsystem/
+.docsystem.local.toml
 /.claude/
 /.paradigmarium/
 /.orchestrator/

{documentation_engine-0.1.2 → documentation_engine-0.2.0}/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to Documentation Engine are documented in this file.
 
+## [0.2.0] - 2026-07-13
+
+### Highlights
+
+- Local workspace source selection lets one checkout address an independent
+  public or private Documentation Engine profile by a stable source name,
+  without committing machine-specific absolute paths.
+- A strict `workspace.toml` registry and ignored `.docsystem.local.toml`
+  pointer provide deterministic discovery through explicit CLI options, an
+  environment variable or local project wiring.
+- New read-only `workspace list` and `workspace doctor` commands report source
+  visibility and availability without reading document bodies or exposing
+  local paths.
+- Existing project commands and MCP tools can select one registered source;
+  explicit selection fails closed and never falls back to the positional
+  project.
+- Source roots must be contained, unique and non-overlapping. Writable
+  documentation and projection paths cannot escape through symlinks, and
+  malformed or looping paths produce bounded diagnostics instead of stack
+  traces.
+- Existing single-project CLI and MCP behavior remains unchanged when no
+  source is selected. This release deliberately does not claim cross-source
+  graph federation, remote storage, synchronization or authorization.
+
 ## [0.1.2] - 2026-07-13
 
 ### Fixed
@@ -52,6 +76,7 @@ documentation-engine` starts working only after the first successful release.
 - Measured context-reduction methodology and a reproducible consumer-install
   smoke test.
 
-[0.1.2]: https://github.com/Jafa7/DocumentationEngine/compare/v0.1.1...main
+[0.2.0]: https://github.com/Jafa7/DocumentationEngine/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/Jafa7/DocumentationEngine/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/Jafa7/DocumentationEngine/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/Jafa7/DocumentationEngine/releases/tag/v0.1.0

{documentation_engine-0.1.2 → documentation_engine-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: documentation-engine
-Version: 0.1.2
+Version: 0.2.0
 Summary: Provider-neutral structured Markdown documentation engine.
 Project-URL: Repository, https://github.com/Jafa7/DocumentationEngine
 Project-URL: Documentation, https://github.com/Jafa7/DocumentationEngine/tree/main/docs
@@ -94,6 +94,12 @@ Ask me where local disaster-recovery backups should be stored before touching
 ignored/private documentation or local configuration.
 ```
 
+If public documentation stays in product repositories while private profiles
+live in one local directory, use [workspace source selection](docs/workspace-sources.md)
+to register those independent profiles and address one by name. This removes
+machine-specific paths from routine commands without claiming a federated
+cross-project graph.
+
 ## Principles
 
 - Markdown is the editable source of truth.
@@ -187,6 +193,9 @@ python -m docsystem changes .
 python -m docsystem changes . --json
 python -m docsystem agent-instructions .
 python -m docsystem agent-instructions . --json
+python -m docsystem workspace list . --workspace /path/to/workspace
+python -m docsystem workspace doctor . --workspace /path/to/workspace
+python -m docsystem context DOC-001 . --source example-project
 ```
 
 `init` creates a project-local `.docsystem.toml` and the configured

{documentation_engine-0.1.2 → documentation_engine-0.2.0}/README.md

@@ -77,6 +77,12 @@ Ask me where local disaster-recovery backups should be stored before touching
 ignored/private documentation or local configuration.
 ```
 
+If public documentation stays in product repositories while private profiles
+live in one local directory, use [workspace source selection](docs/workspace-sources.md)
+to register those independent profiles and address one by name. This removes
+machine-specific paths from routine commands without claiming a federated
+cross-project graph.
+
 ## Principles
 
 - Markdown is the editable source of truth.
@@ -170,6 +176,9 @@ python -m docsystem changes .
 python -m docsystem changes . --json
 python -m docsystem agent-instructions .
 python -m docsystem agent-instructions . --json
+python -m docsystem workspace list . --workspace /path/to/workspace
+python -m docsystem workspace doctor . --workspace /path/to/workspace
+python -m docsystem context DOC-001 . --source example-project
 ```
 
 `init` creates a project-local `.docsystem.toml` and the configured

{documentation_engine-0.1.2 → documentation_engine-0.2.0}/docs/adoption.md

@@ -146,6 +146,12 @@ delete or migration mistake. Define a local backup command before letting an
 agent perform broad or mutating work on ignored documentation. The reusable
 contract is described in [local state safety](local-state-safety.md).
 
+When several independent public or private profiles live under one local
+documentation directory, register them with
+[workspace source selection](workspace-sources.md). The registry selects one
+ordinary profile by name; it does not merge catalogs or authorize deleting an
+original `plan/` after a copy-only migration.
+
 Project-specific registry synchronization, `finish` orchestration, private
 history/backup, and provider adapters remain outside this adoption profile.
 

{documentation_engine-0.1.2 → documentation_engine-0.2.0}/docs/agent-contract.md

@@ -77,6 +77,13 @@ unrelated directories, and an implicit-cwd invocation against the wrong
 directory produces a confusing `configuration not found` error at best and
 operates on an unintended project at worst.
 
+For a profile registered in a local documentation workspace, an agent must
+instead pass the positional discovery root and `--source NAME`. Workspace
+resolution is fail-closed: an unknown or unavailable source must never be
+replaced with the positional project. The local pointer and absolute workspace
+path are private machine wiring and must not be committed. See
+[workspace source selection](workspace-sources.md).
+
 ## Prefer `--json` over parsing text
 
 `readiness`, `migration-report`, `catalog --explain`, `changes` and

{documentation_engine-0.1.2 → documentation_engine-0.2.0}/docs/architecture.md

@@ -62,6 +62,12 @@ Project policy may configure:
 - legacy path-relation migration and historical snapshot document types;
 - provider adapters.
 
+A local workspace registry is an outer selection layer, not another project
+configuration table. It maps a stable source name to one contained project
+root, after which the existing configuration, catalog, graph and projection
+contracts apply unchanged. It deliberately does not aggregate multiple
+sources; see [workspace source selection](workspace-sources.md).
+
 ## Scalable projection
 
 The target projection is sharded and generation-based:
@@ -265,3 +271,5 @@ fall back to the default, while a configured non-H2 match is invalid.
 6. Thin Codex integration and generated agent instructions.
 7. MCP adapter (an initial read-only stdio adapter ships as
    `docsystem.mcp_server`) and additional client integrations.
+8. Local workspace source selection for independently owned profiles, before
+   any atomic cross-source federation design.

{documentation_engine-0.1.2 → documentation_engine-0.2.0}/docs/mcp-adapter.md

@@ -71,10 +71,17 @@ The adapter is deliberately a wrapper, not a second implementation:
 | `impact` | text (Markdown table) | `docsystem impact ID PROJECT` |
 | `impact_packet` | object | `docsystem impact ID PROJECT` |
 | `agent_instructions` | object | `docsystem agent-instructions PROJECT --json` |
+| `workspace_list` | object | `docsystem workspace list PROJECT --json` |
 
 Every tool takes the project root explicitly; none relies on the server
 process working directory.
 
+Project-oriented tools also accept optional `source` and `workspace`
+parameters for [workspace source selection](workspace-sources.md). They append
+the corresponding CLI flags only when provided, so existing MCP calls remain
+unchanged. `workspace_list` reports registry metadata without reading document
+bodies. The adapter does not federate sources or expose workspace mutations.
+
 The packet tools use this envelope:
 
 ```json

documentation_engine-0.2.0/docs/workspace-sources.md

@@ -0,0 +1,155 @@
+# Workspace source selection
+
+Documentation Engine normally operates on one project root passed directly to
+each command. A local documentation workspace can register several independent
+project profiles and let a caller select one by a stable source name instead
+of repeating a machine-specific absolute path.
+
+This feature is source selection, not federation. One command still sees one
+ordinary catalog, dependency graph and projection. It does not merge IDs,
+relations or context across sources.
+
+## Ownership model
+
+Keep public product documentation in the repository that owns it. A private
+workspace may hold ignored planning documents, internal reviews and other
+local-only profiles outside public repositories. Each registered source is a
+complete Documentation Engine project root with its own `.docsystem.toml`,
+Markdown root and disposable `.docsystem/` projection.
+
+The workspace registry does not copy, move, synchronize or delete documents.
+Markdown ownership remains with the selected source. In particular, moving a
+profile into a workspace is a separate, owner-controlled, copy-only migration:
+the engine never authorizes removal of the original source tree.
+
+## Registry
+
+Create `workspace.toml` at the root of the local workspace:
+
+```toml
+version = 1
+
+[[sources]]
+name = "example-project"
+root = "projects/example-project"
+visibility = "private"
+
+[[sources]]
+name = "shared-guides"
+root = "projects/shared-guides"
+visibility = "public"
+```
+
+Every source root is relative to the workspace, must remain inside it after
+symlink resolution, and must name a complete project profile. Its configured
+documentation root and projection cache must also resolve inside that source;
+a writable symlink escape makes the source unavailable. Source names use
+lowercase ASCII letters, digits and hyphens, starting with a letter. Names and
+resolved roots must be unique and non-overlapping. `visibility` is required
+and is either `private` or `public`.
+
+Visibility is inspectable metadata in this milestone. It does not implement
+authorization or redaction: selecting a private source explicitly means the
+local caller is allowed to read it. Do not expose a workspace through an
+untrusted service or publish generated output without applying the
+organization's access policy.
+
+Inspect the registry without reading document bodies:
+
+```bash
+docsystem workspace list . --workspace /path/to/documentation-workspace
+docsystem workspace list . --workspace /path/to/documentation-workspace --json
+docsystem workspace doctor . --workspace /path/to/documentation-workspace
+```
+
+The listing contains only source name, visibility, availability and a fixed
+reason slug. Missing roots, missing or invalid configurations and unsafe local
+paths remain visible; selecting any unavailable source fails closed.
+
+## Local project pointer
+
+For routine use, place this ignored file in the consuming checkout:
+
+```toml
+# .docsystem.local.toml
+workspace = "/path/to/documentation-workspace"
+```
+
+The pointer is local machine wiring, not public project policy. It accepts one
+absolute path and is ignored by the Documentation Engine repository template.
+Do not commit it or paste its value into public agent instructions.
+
+Workspace discovery uses this precedence:
+
+1. `--workspace PATH`;
+2. `DOCSYSTEM_WORKSPACE`;
+3. `.docsystem.local.toml` in the positional project root.
+
+An explicit source never falls back to the positional project when discovery,
+manifest validation or source availability fails.
+
+## Selecting a source
+
+Commands that operate on an existing project profile accept `--source NAME`
+and `--workspace PATH`:
+
+```bash
+docsystem readiness . --source example-project --json
+docsystem catalog . --source example-project
+docsystem context DOC-001 . --source example-project --depth 1
+docsystem impact DOC-001 . --source example-project
+docsystem index . --source example-project --write
+```
+
+`--workspace` is normally omitted after installing the local pointer. On a
+project command it is valid only together with `--source`. The `report draft`
+command already uses `--source` for the reporting host, so its workspace
+selector is spelled `--workspace-source`:
+
+```bash
+docsystem report draft . \
+  --project-name "Example" \
+  --type adoption-finding \
+  --source codex \
+  --workspace-source example-project
+```
+
+`init` remains a direct-path bootstrap command. Create a new profile with
+`docsystem init PATH`, then register that valid project root in
+`workspace.toml`; source selection never creates or repairs workspace entries.
+
+When no source selector is present, workspace state is not loaded or validated
+and the existing single-project behavior is unchanged. Selected-source
+readiness and agent-instruction output identify the project by the caller's
+positional discovery root plus `--source NAME`, never by the private source
+root. Generated next commands therefore remain directly executable while the
+same local pointer or environment wiring is active.
+
+Mutating commands retain their existing authorization boundary. Source
+selection does not make `init`, `migrate --apply` or `index --write` read-only;
+it only changes the one project root they target. Agents must still obtain the
+required approval and backup local-only authored state first.
+
+## MCP
+
+The read-only MCP tools accept optional `source` and `workspace` parameters.
+They forward the same CLI flags and preserve the old invocation exactly when
+both are omitted. `workspace_list` exposes the body-free registry listing.
+MCP does not expose workspace creation, synchronization, migration or source
+mutation.
+
+## Deliberate non-goals
+
+This milestone does not provide:
+
+- qualified cross-project document IDs;
+- cross-source dependency edges or aggregate context;
+- a workspace-level projection;
+- remote/network sources, authentication or authorization;
+- concurrent-write locking;
+- Git synchronization, import, copy or deletion;
+- a documentation web server or UI.
+
+Those capabilities require one atomic federation design. Until then, a caller
+that needs another project selects that source in a separate command and must
+not infer a complete cross-project graph.

{documentation_engine-0.1.2 → documentation_engine-0.2.0}/src/docsystem/__init__.py

@@ -9,7 +9,7 @@ from docsystem.catalog import (
 from docsystem.metadata import DocumentMetadata, MetadataReference
 from docsystem.sections import MarkdownSection
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"
 
 __all__ = [
     "CatalogMembership",