chore: prepare v0.8 api freeze

Author: Developer

.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  required:
+    name: required checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Restore Cargo cache
+        uses: Swatinem/rust-cache@v2
+
+      - name: Check formatting
+        run: cargo fmt --check
+
+      - name: Clippy
+        run: cargo clippy --workspace --all-targets -- -D warnings
+
+      - name: Test workspace
+        run: cargo test --workspace --locked --no-fail-fast
+
+      - name: Build CLI for smoke gates
+        run: cargo build --locked -p llmff
+
+      - name: Schema contract
+        run: python3 scripts/check-schema-contract.py
+
+      - name: Plugin fixtures
+        run: bash scripts/check-plugin-fixtures.sh
+
+      - name: Governance readiness
+        run: bash scripts/check-governance-readiness.sh
+
+      - name: Ecosystem readiness
+        run: bash scripts/check-ecosystem-readiness.sh
+
+      - name: Real-world workflow examples
+        run: bash scripts/check-real-world-workflows.sh
+        env:
+          LLMFF_BIN: target/debug/llmff
+
+      - name: Events and streaming smoke
+        run: LLMFF_BIN=target/debug/llmff bash scripts/smoke-events-streaming.sh

CONTRIBUTING.md

@@ -12,12 +12,26 @@ opening a release-facing pull request.
 Useful gates:
 
 ```bash
+cargo fmt --check
+cargo clippy --workspace --all-targets -- -D warnings
 cargo test
-scripts/check-schema-contract.py
-scripts/check-plugin-fixtures.sh
-scripts/check-governance-readiness.sh
+python3 scripts/check-schema-contract.py
+bash scripts/check-plugin-fixtures.sh
+bash scripts/check-governance-readiness.sh
 ```
 
+Release-facing pull requests should also run the CI-equivalent local gate:
+
+```bash
+cargo test --workspace --locked --no-fail-fast
+bash scripts/check-ecosystem-readiness.sh
+bash scripts/check-real-world-workflows.sh
+LLMFF_BIN=target/debug/llmff bash scripts/smoke-events-streaming.sh
+```
+
+Live provider smoke checks remain explicit and opt-in; do not require provider
+secrets for ordinary pull requests.
+
 For release packaging or distribution docs, also run the relevant shell gate
 from `scripts/`.
 
@@ -79,3 +93,19 @@ the channel is support-ready.
 
 Deprecations must follow `docs/governance.md`: document the replacement,
 warning behavior when practical, release-note impact, and removal timing.
+
+## Deprecating Public Surface
+
+Before deprecating a public manifest field, CLI flag, plugin protocol behavior,
+trace/event field, run-directory artifact, provider configuration key, package
+metadata channel, or library API:
+
+- identify whether the change is patch, minor, or major under
+  `docs/governance.md`;
+- write the replacement or explain why there is no replacement;
+- add tests, fixtures, schemas, or docs for the old and new behavior during the
+  deprecation window;
+- add release-note coverage with first deprecated release and earliest removal
+  timing;
+- keep warnings or diagnostics actionable and avoid breaking automation unless
+  the old behavior is unsafe.

Cargo.lock

@@ -9,7 +9,7 @@ resolver = "2"
 edition = "2021"
 license = "MIT"
 repository = "https://github.com/syndicalt/llmff"
-version = "0.1.6"
+version = "0.8.0"
 
 [workspace.dependencies]
 anyhow = "1"

Cargo.toml

@@ -7,8 +7,12 @@
 ## Start Here
 
 - New users: follow [`docs/quickstart.md`](docs/quickstart.md).
+- Deciding fit: read [`docs/when-to-use-llmff.md`](docs/when-to-use-llmff.md).
 - Example catalog: see [`examples/README.md`](examples/README.md).
+- Pattern cookbook: see [`docs/cookbook.md`](docs/cookbook.md).
 - Agent integrations: see [`docs/agent-workflows.md`](docs/agent-workflows.md).
+- Pre-1.0 migration checklist: see
+  [`docs/migration/pre-1.0-to-1.0.md`](docs/migration/pre-1.0-to-1.0.md).
 - Platform packages and installer assumptions: see
   [`docs/platform-support.md`](docs/platform-support.md).
 
@@ -20,10 +24,11 @@ Install from GitHub:
 cargo install --git https://github.com/syndicalt/llmff llmff
 ```
 
-Install a tagged release:
+After the `v0.8.0` release-candidate tag is published, install that tagged
+release with:
 
 ```bash
-cargo install --git https://github.com/syndicalt/llmff --tag v0.1.6 llmff
+cargo install --git https://github.com/syndicalt/llmff --tag v0.8.0 llmff
 ```
 
 For a local checkout:
@@ -39,6 +44,17 @@ llmff --version
 llmff stages list
 ```
 
+Check local prerequisites without running a pipeline or calling provider
+endpoints:
+
+```bash
+llmff doctor \
+  --run-dir .llmff/run \
+  --plugin-dir ./plugins \
+  --backend openai=https://api.openai.com/v1 \
+  --api-key-env openai=OPENAI_API_KEY
+```
+
 Supported release targets and installer assumptions are documented in
 [`docs/platform-support.md`](docs/platform-support.md).
 
@@ -51,32 +67,33 @@ scripts/smoke-install.sh --path .
 Smoke test a generated release archive without installing:
 
 ```bash
-scripts/smoke-archive.sh --archive dist/llmff-0.1.6-x86_64-unknown-linux-gnu.tar.gz
+scripts/smoke-archive.sh --archive dist/llmff-0.8.0-x86_64-unknown-linux-gnu.tar.gz
 ```
 
 Run the release metadata preflight before creating or pushing a release tag:
 
 ```bash
-scripts/release-preflight.sh v0.1.6
+scripts/release-preflight.sh v0.8.0
 ```
 
-Verify a published release's assets, checksums, and host-compatible packages:
+After release-tag CI completes, verify a published release's assets, checksums,
+and host-compatible packages:
 
 ```bash
-scripts/check-release-assets.sh v0.1.6
+scripts/check-release-assets.sh v0.8.0
 ```
 
 Generate and validate Windows MSI packaging metadata:
 
 ```bash
-scripts/package-windows-msi.sh --binary target/release/llmff.exe --version 0.1.6 --target x86_64-pc-windows-msvc --out-dir dist --emit-wxs-only
+scripts/package-windows-msi.sh --binary target/release/llmff.exe --version 0.8.0 --target x86_64-pc-windows-msvc --out-dir dist --emit-wxs-only
 ```
 
 Build a Windows MSI on a Windows host:
 
 ```bash
 dotnet tool restore
-scripts/package-windows-msi.sh --binary target/release/llmff.exe --version 0.1.6 --target x86_64-pc-windows-msvc --out-dir dist
+scripts/package-windows-msi.sh --binary target/release/llmff.exe --version 0.8.0 --target x86_64-pc-windows-msvc --out-dir dist
 ```
 
 Smoke test a staged Windows MSI payload without installing:
@@ -88,19 +105,19 @@ scripts/smoke-windows-msi.sh --payload-root dist/windows-msi-smoke-root
 Generate and validate macOS installer payload metadata:
 
 ```bash
-scripts/package-macos-pkg.sh --binary target/release/llmff --version 0.1.6 --target aarch64-apple-darwin --out-dir dist --emit-payload-only
+scripts/package-macos-pkg.sh --binary target/release/llmff --version 0.8.0 --target aarch64-apple-darwin --out-dir dist --emit-payload-only
 ```
 
 Smoke test a generated macOS installer payload without installing:
 
 ```bash
-scripts/smoke-macos-pkg.sh --payload-root dist/llmff-0.1.6-aarch64-apple-darwin.pkgroot
+scripts/smoke-macos-pkg.sh --payload-root dist/llmff-0.8.0-aarch64-apple-darwin.pkgroot
 ```
 
 Smoke test a generated Debian package without root:
 
 ```bash
-scripts/smoke-deb.sh --deb dist/llmff_0.1.6_amd64.deb
+scripts/smoke-deb.sh --deb dist/llmff_0.8.0_amd64.deb
 ```
 
 Release tags build compressed binary archives, Ubuntu/Debian `.deb` packages, Arch `PKGBUILD` metadata, unsigned Windows MSI packages, and unsigned macOS `.pkg` packages in CI. Trusted Windows Authenticode signing and Apple Developer ID signing/notarization are deferred until paid credentials are available. See [`docs/platform-support.md`](docs/platform-support.md) for the current target matrix.
@@ -118,6 +135,7 @@ Tagged release builds publish archives, checksums, `.deb` packages, Arch metadat
 - `llmff models list --format json` prints runtime model metadata for built-in mock models, CLI-registered OpenAI-compatible or Ollama aliases, and plugin command backends.
 - `llmff plugins list --plugin-dir <path>` discovers `llmff-plugin.yaml` manifests and prints plugin capability metadata.
 - `llmff run --plugin-dir <path>` can execute plugin-provided stages, backends, and tool transports declared in those manifests.
+- `llmff doctor` checks local prerequisites such as binary version, run-dir writability, plugin manifest validity, API-key environment wiring, and optional release trust manifest presence without making network calls.
 - The core crate owns execution semantics; the CLI is a thin adapter.
 - Mock backends are available for deterministic local runs and tests.
 - An OpenAI-compatible backend exists in the core crate for `/v1/chat/completions` servers.

README.md

@@ -6,6 +6,12 @@ This is the canonical product boundary and roadmap document for `llmff`.
 pipelines. It executes declared manifests and graphs; it does not plan work,
 own memory, coordinate agents, or act as an agent framework.
 
+First-reader decision guidance lives in
+[`docs/when-to-use-llmff.md`](docs/when-to-use-llmff.md). Workflow recipes live
+in [`docs/cookbook.md`](docs/cookbook.md), and the pre-1.0 compatibility
+checklist lives in
+[`docs/migration/pre-1.0-to-1.0.md`](docs/migration/pre-1.0-to-1.0.md).
+
 ## Current Implementation
 
 `llmff` is currently a command-line and library runner for typed LLM inference