docs: align dependency and framework guidance

README.md

@@ -39,16 +39,12 @@ $ northstar --quiet status
 
 ### Install an existing release
 
-To install the first published demo release without cloning the repository:
-
-```bash
-python -m pip install \
-  "https://github.com/basefoundry/base-cli-demo/releases/download/v0.1.0/base_cli_demo-0.1.0-py3-none-any.whl"
-```
-
-Verify the artifact against `SHA256SUMS.txt` on the same GitHub Release. The
-wheel depends on the released `base-cli>=0.4.3,<0.5` API line; it does not
-install Base or require a Base workspace.
+The first immutable demo release is not published yet. The documented
+from-source install above is the supported path until
+[#28](https://github.com/basefoundry/base-cli-demo/issues/28) completes the
+release readiness gates. After publication, this section should be restored
+with the verified wheel URL, checksum, and matching `base-cli` dependency line;
+do not infer a release from the source `VERSION` file.
 
 The default environment is `dev`. Select another fixture environment with the
 framework lifecycle option:
@@ -142,8 +138,9 @@ python -m pip install ".[dev]"
 ```
 
 The package requires Python 3.10 or newer and pins the supported Base-CLI line
-to `>=0.4.3,<0.5`. This checkout targets demo release `v0.1.0`; demo release
-versioning remains separate from framework versioning.
+to `>=0.4.3,<0.5`. This checkout carries source version `0.1.0`; immutable
+publication is tracked separately in #28, and demo release versioning remains
+independent from framework versioning.
 
 ## Documentation
 
@@ -154,8 +151,8 @@ release. To start with a minimal consumer rather than the full demo, use the
 
 For framework-level material, start at the
 [Base-CLI repository](https://github.com/basefoundry/base-cli), its
-[getting-started guide](https://github.com/basefoundry/base-cli#quick-start),
-or the [public API reference](https://github.com/basefoundry/base-cli/blob/main/docs/api-reference.md).
+[getting-started guide](https://github.com/basefoundry/base-cli/blob/v0.4.3/README.md#quick-start),
+or the [public API reference](https://github.com/basefoundry/base-cli/blob/v0.4.3/docs/api-reference.md).
 
 ## Repository shape
 

docs/README.md

@@ -24,5 +24,5 @@ the complete Northstar consumer:
 
 For the framework's complete material, start at the
 [Base-CLI repository](https://github.com/basefoundry/base-cli), its
-[getting-started guide](https://github.com/basefoundry/base-cli#quick-start),
-or the [public API reference](https://github.com/basefoundry/base-cli/blob/main/docs/api-reference.md).
+[getting-started guide](https://github.com/basefoundry/base-cli/blob/v0.4.3/README.md#quick-start),
+or the [public API reference](https://github.com/basefoundry/base-cli/blob/v0.4.3/docs/api-reference.md).

docs/learning-path.md

@@ -103,10 +103,10 @@ Open `src/base_cli_demo/cli.py` while following the examples:
   repository conventions mandatory.
 
 For deeper framework context, continue with the Base-CLI
-[API reference](https://github.com/basefoundry/base-cli/blob/main/docs/api-reference.md),
-[consumer profiles](https://github.com/basefoundry/base-cli/blob/main/docs/consumer-profiles.md),
-[output contracts](https://github.com/basefoundry/base-cli/blob/main/docs/output-contracts.md),
-[JSON contracts](https://github.com/basefoundry/base-cli/blob/main/docs/json-contracts.md),
+[API reference](https://github.com/basefoundry/base-cli/blob/v0.4.3/docs/api-reference.md),
+[consumer profiles](https://github.com/basefoundry/base-cli/blob/v0.4.3/docs/consumer-profiles.md),
+[output contracts](https://github.com/basefoundry/base-cli/blob/v0.4.3/docs/output-contracts.md),
+[JSON contracts](https://github.com/basefoundry/base-cli/blob/v0.4.3/docs/json-contracts.md),
 and [testing guide](https://github.com/basefoundry/base-cli/blob/main/docs/testing.md).
 
 ## Current behavior and future scope

docs/should-i-use-base-cli.md

@@ -7,10 +7,12 @@ is pre-1.0 and classified as Beta. The demo currently tests the released
 `>=0.4.3,<0.5` line. This is not a promise that every future pre-1.0 minor line
 is compatible: Base-CLI's published policy treats patch releases as compatible
 and allows a minor release before 1.0 to be a compatibility boundary. Read the
-[API stability policy](https://github.com/basefoundry/base-cli/blob/main/docs/api-stability.md)
-and [migration notes](https://github.com/basefoundry/base-cli/blob/main/docs/migrations.md)
+[API stability policy](https://github.com/basefoundry/base-cli/blob/v0.4.3/docs/api-stability.md)
+and [migration notes](https://github.com/basefoundry/base-cli/blob/v0.4.3/docs/migrations.md)
 when changing the dependency range. The demo's lockfile records a reproducible
-resolved environment; library consumers should choose a range that matches
+resolved environment; readers moving to the 0.5 line should also read the
+[0.5 migration notes](https://github.com/basefoundry/base-cli/blob/main/docs/migration-0.5.md).
+Library consumers should choose a range that matches
 their own upgrade policy.
 
 Base-CLI does not replace Click or Typer. It composes with their command
@@ -61,7 +63,7 @@ does not follow a future 0.5 line automatically.
 | Base-CLI with Click or Typer | A shared lifecycle and documented automation/output boundary around a familiar parser. | One more dependency, an integration model to learn, and compatibility work as the framework evolves. |
 
 For the parser-focused comparison maintained by the framework project, see its
-[framework choice guide](https://github.com/basefoundry/base-cli/blob/main/docs/framework-choice.md).
+[framework choice guide](https://github.com/basefoundry/base-cli/blob/v0.4.3/docs/framework-choice.md).
 For primary references, see the official
 [argparse documentation](https://docs.python.org/3/library/argparse.html),
 [Click documentation](https://click.palletsprojects.com/), and

docs/use-in-your-project.md

@@ -7,7 +7,7 @@ invocation lifecycle.
 Install the released framework line used by this demo:
 
 ```bash
-python -m pip install "base-cli>=0.4.3,<0.5" "click>=8.1,<9"
+python -m pip install "base-cli>=0.4.3,<0.5" "click>=8.1,<8.6"
 ```
 
 Save this as `hello.py`:
@@ -48,5 +48,5 @@ consumer-owned configuration, and structured output.
 The `App` and `attach` calls establish the framework boundary; the Click
 function remains your command. See the framework's
 [consumer quickstart](https://github.com/basefoundry/base-cli/blob/main/docs/consumer-quickstart.md)
-and [API reference](https://github.com/basefoundry/base-cli/blob/main/docs/api-reference.md)
+and [API reference](https://github.com/basefoundry/base-cli/blob/v0.4.3/docs/api-reference.md)
 for the public interfaces.

docs/yaml-output.md

@@ -2,10 +2,10 @@
 
 YAML is a supported Base-CLI renderer, but it is intentionally not part of the
 demo's minimal dependencies. Install the optional extra before using
-`--format yaml`:
+`--format yaml`. Run this command from the repository root:
 
 ```console
-$ python -m pip install "base-cli-demo[yaml]"
+$ python -m pip install ".[yaml]"
 $ northstar --quiet status --format yaml
 ```
 

tests/test_documentation.py

@@ -31,3 +31,16 @@ def test_documented_northstar_commands_are_executable(
         result = base_cli.testing.invoke(command, args[1:], home=Path(directory))
 
     assert result.exit_code == 0, f"{document}: {args!r}\n{result.output}"
+
+
+def test_documented_dependency_windows_match_project_metadata() -> None:
+    metadata = Path("pyproject.toml").read_text(encoding="utf-8")
+    starter = Path("docs/use-in-your-project.md").read_text(encoding="utf-8")
+
+    for requirement in ('"base-cli>=0.4.3,<0.5"', '"click>=8.1,<8.6"'):
+        assert requirement in metadata
+        assert requirement.strip('"') in starter
+
+    yaml_guide = Path("docs/yaml-output.md").read_text(encoding="utf-8")
+    assert 'python -m pip install ".[yaml]"' in yaml_guide
+    assert 'base-cli-demo[yaml]' not in yaml_guide