ai-kit-python 1.4.2__py3-none-any.whl

aikit/docs/V1_4_1.md

@@ -0,0 +1,55 @@
+# AI-KIT v1.4.1
+
+Release date: 2026-10-15. [CHANGELOG](../CHANGELOG.md#v141-2026-10-15) owns release history. This patch updates Docker maintenance and distribution privacy on top of [v1.4.0](V1_4_0.md).
+
+## Release contents
+
+- Docker image freshness is part of normal maintenance. When a project has images, installed AGENTS asks the agent to assess changes, update build inputs where needed, rebuild affected images and test their actual behavior. [Canonical policy](../template/ai-kit/CONTAINERS.md#image-freshness), [maintainer procedure](DOCKER.md#change-impact-and-image-refresh).
+- Root maintainer `AGENTS.md`, `PROJECT_CONTEXT.md` and `WIKI.md` stay local and untracked. The Docker build context, wheel and source distribution exclude them. Public maintenance starts at [CONTRIBUTING](../CONTRIBUTING.md); clean distributions validate without these optional local files.
+- Application templates retain their own three documents. Existing project context, preferences, private dialogue memory, local skill edits and native client configuration keep their normal preservation/conflict rules.
+- Regression checks cover root-file exclusion, template inclusion, public links, actual Docker ignore behavior and offline wheel installation. Shared dialogue context and the optional security/design integrations retain their v1.4.0 contracts.
+
+Ignoring an already tracked file does not remove it from Git's index. These root files have been untracked while preserving their local copies. This affects future commits and new packages; it does not erase past Git history or replace previously published images. Root README has no size quota; other instruction budgets remain scoped.
+
+## Use the versioned image
+
+Published image: [tigusigalpa/ai-kit:1.4.1](https://hub.docker.com/r/tigusigalpa/ai-kit/tags?name=1.4.1), for `linux/amd64`. The immutable digest is recorded below after successful upload and independent read-back.
+
+~~~sh
+docker pull tigusigalpa/ai-kit:1.4.1
+docker run --rm --init --network none --read-only --cap-drop ALL \
+  --security-opt no-new-privileges --tmpfs /tmp:rw,nosuid,nodev,size=256m \
+  tigusigalpa/ai-kit:1.4.1 --help
+~~~
+
+For installation, mount an application at `/workspace` and follow [preview/apply instructions](../README.md#run-ai-kit-with-docker). The image uses UID/GID 10001:10001 and entrypoint `aikit`. Keep raw conversations and application data in runtime mounts.
+
+## Verification
+
+Before release labeling, Windows/Python 3.12.14 passed 27 checker tests. The packaged Linux/Python 3.13.16 discovery ran 339 tests: 337 passed and two Windows-junction tests skipped. Kit validation, isolated wheel/source-distribution exclusion, offline fresh-venv installation and actual Docker smoke passed. The new image omitted exactly the three root maintainer documents compared with the preceding published image; their template counterparts remained included.
+
+After labeling as 1.4.1, verified on 2026-10-15:
+
+- VERSION, CLI, wheel metadata and the image label agree on 1.4.1. Windows/Python 3.12.14 passed nine CLI tests; kit validation returned zero errors and warnings.
+- The actual non-root, offline, read-only Linux/Python 3.13.16 image ran all 339 tests in 28.697 seconds: 337 passed and two Windows-junction tests skipped.
+- Docker smoke passed preview/apply, read-only refusal, all four optional modules, preserved documents, doctor, design context, stable rerun and SIGTERM. Docker's actual ignore engine excluded synthetic private files and the root maintainer documents while retaining their template counterparts.
+- Isolated wheel and source-distribution builds excluded synthetic local root files and their marker; application templates remained present. Offline installation into a fresh Windows venv passed the CLI, memory import/merge/export pipeline, kit validation and optional resource checks. Every image payload file matched the wheel and public sources byte for byte. The wheel also retained three existing public compatibility entry points outside the Docker allowlist (CLAUDE.md, KIMI.md and MANUS.md); artifact counts and hashes are retained outside the checkout.
+- Upgrade fixtures used a Git archive of tracked HEAD at 1.4.0, rather than a reconstructed published package. Private/team modes preserved project facts, unknown settings, design documents, local skill edits, MCP configuration, private dialogue memory and both security pin identities. A local skill conflict caused by archive/checkout newlines remained reviewable and was explicitly accepted only after checking equivalent canonical text. VERSION/state advanced to 1.4.1; doctor, links, private Git visibility and stable reruns passed.
+- Test containers were removed; no test volumes were created. The shared desktop-linux builder did not establish project-owned cache size, so no shared cache or volume prune was performed.
+
+The complete Windows checker run preceded labeling; the post-label full discovery ran in the packaged Linux image. Publication and test-result receipts were added to source docs afterward. They change descriptive status only: the retained image/wheel contain the tested pre-publication documentation snapshot. No rebuild or tag replacement was needed for this receipt. The external artifact folder retains artifacts.json, verification.json, publication.json, SHA256SUMS, wheel, source archive and logs.
+
+Local checks do not establish hosted CI, macOS execution, another CPU architecture, live model/client activation or a Kubernetes deployment. No Git commit, push, tag or GitHub release is part of this preparation.
+
+## Docker Hub publication
+
+Published on 2026-10-15 at the owner's explicit request. The successful push, independent registry inspection and anonymous Docker Hub API returned the same index digest as the prepared image.
+
+- Registry index digest: `sha256:d11fc24026f13ad90d3ef7a39a235fa40db29ff022999cff3585e7e707978370`.
+- Runtime platform: `linux/amd64`; platform manifest: `sha256:d20bfd27b8ecd276ea3f0a0e8bd3fa1e39b4fe9663ef679ef98befe1f3023361`.
+- Remote configuration: version 1.4.1, UID/GID 10001:10001 and entrypoint aikit. Build attestation metadata is not another runtime architecture.
+- Only tag 1.4.1 was pushed. The preceding 1.4.0 identity was preserved; latest was not assigned.
+
+~~~sh
+docker pull tigusigalpa/ai-kit@sha256:d11fc24026f13ad90d3ef7a39a235fa40db29ff022999cff3585e7e707978370
+~~~

aikit/docs/V1_4_2.md

@@ -0,0 +1,33 @@
+# AI-KIT v1.4.2
+
+Release preparation date: 2026-10-16. [CHANGELOG](../CHANGELOG.md#v142-2026-10-16) owns release history; [PyPI procedure](PYPI.md) owns publishing instructions.
+
+## Release contents
+
+- First Python registry distribution: `ai-kit-python`, import package and command `aikit`, Python 3.10+ and no mandatory runtime dependencies.
+- Portable Markdown description, project metadata and complete bundled MIT/Apache-2.0 license files.
+- Isolated source archive followed by a wheel built from it; metadata, resource, privacy, path and offline-installation checks.
+- Manual Trusted Publishing: validation is the default; uploads require the exact version/tag and canonical repository, job-scoped OIDC and validated same-run artifacts.
+- Tested `aikit --version`, a README Docker Hub badge and the saved Docker Hub Overview with its release-maintenance rule.
+
+The existing Git tag `v1.4.1` predates PyPI publishing support. Version 1.4.2 gives the new release a separate source identity. The published Docker image remains `tigusigalpa/ai-kit:1.4.1`; replacing it is outside this PyPI request.
+
+## Verified preparation
+
+Final `ai-kit-python` preparation passed kit validation with zero errors/warnings, thirteen Windows archive/identity tests, isolated private-probe builds, strict Twine checks, offline Windows wheel installation and 353 packaged Linux tests (351 passed, two Windows-only skips, 27.652 seconds). Ten Windows CLI tests also passed earlier at the same version. Resource checks excluded root private maintainer files and retained application templates. Actual Docker smoke passed after the final name change.
+
+Docker smoke covers offline/read-only operation, preview/refusal, all optional modules, preservation, doctor, design context, stable rerun, SIGTERM and Docker's actual context-exclusion engine. No test volumes were created; temporary test containers were removed. Shared cache ownership is unknown, so no pruning was performed. Descriptive verification/publication receipts added after building remain outside the tested documentation snapshot.
+
+## Publishing setup and status
+
+PyPI rejected `ai-kit` and `ai-kit-cli` as too similar to existing projects. The owner selected `ai-kit-python`; its pending Trusted Publisher was registered and visibly read back on 2026-10-16:
+
+- GitHub repository: `tigusigalpa/ai-kit`.
+- Workflow: `publish-pypi.yml`.
+- Environment: `pypi`.
+
+The GitHub environment was independently read back: only tag `v1.4.2`, required reviewer `tigusigalpa`, self-review permitted for solo maintenance. TestPyPI remains unconfigured and no TestPyPI upload was requested. A pending publisher does not reserve a project name or establish package availability.
+
+The owner authorized commit/push, PR/merge after required checks, creation/push of v1.4.2 and the production PyPI upload. [PR 1](https://github.com/tigusigalpa/ai-kit/pull/1) contains the release. Its first hosted run exposed incorrect Twine wildcard quoting on Windows; the complete glob is now quoted and passed local PowerShell validation with a space-containing path. Hosted checks must finish before merging. No registry upload or public installation is established yet; record the actual workflow/tag identity, uploaded hashes and fresh installation afterward.
+
+[Core](../template/ai-kit/CORE.md#git-authorization) governs Git authorization. No account secrets belong in source, artifacts or chat. Future image publication remains separate; preserve existing release tags and Docker identities.

aikit/docs/WEB_DESIGN.md

@@ -0,0 +1,72 @@
+# Web Design integration record
+
+## Scope and ownership
+
+The optional module turns a brief and annotated references into project design memory, stack-aware implementation and recorded UI acceptance. The [README guide](../README.md#web-design) is human onboarding; [WEB-DESIGN](../template/ai-kit/WEB-DESIGN.md) owns the installed workflow. Conditional references own [Blade implementation](../template/ai-kit/web-design/LARAVEL.md), [libraries](../template/ai-kit/web-design/LIBRARIES.md), [tools](../template/ai-kit/web-design/TOOLS.md) and [UI evidence](../template/ai-kit/web-design/REVIEW.md). Existing Core/engineering/security/stack policies remain canonical.
+
+No external skill/runtime bytes are bundled. Local skills use normal relevant discovery and check `web_design=true`; extraction describes requested reference work without automatically starting a CLI. TypeUI/MCP authentication, external skill/package setup and website publication remain separate actions.
+
+## Installer and context behavior
+
+- `--with-web-design` persists an independent boolean outside presets. Fresh default/preset installations omit all module resources, skills and project documents. Selection supports multiple short entry points for one extra without changing the pinned security packages.
+- Four source skills have matching Claude copies when that client is selected. The installer preserves native MCP configuration and invokes no process/network/runtime during module installation.
+- `docs/design/BRIEF.md`, `SYSTEM.md` and `ACCEPTANCE.md` are created only when missing and preserved byte-for-byte thereafter. Existing project WIKI/context are preserved; bootstrap adds relevant pointers. Doctor checks/restores the enabled module's missing project documents through the normal installer path.
+- Managed module guides/skills use normal local-adaptation/conflict behavior. Disabling selection retains previous files; the setting prevents workflow use/selection, while catalog discovery may still list retained skills. Explicit adapter retirement removes only that client's unchanged tracked files.
+- Design documents stay ordinary project source in both sharing modes. Working output under `ai-kit/.design/` is ignored in private/team modes; already tracked data needs separate review.
+- `context select --workflow web-design|ui-review|design-extract` requires the enabled setting and selects the relevant workflow plus project design documents. Main Web Design selection adds Blade guidance only for the declared Laravel/Filament module. Ordinary selection is unchanged; required files survive byte overruns, and the result is a manifest rather than a prompt.
+- The root README has no byte quota. Existing entry-point and conditional instruction budgets remain scoped to their actual files; link/language/metadata checks still apply to README.
+
+## Recommendation disposition and source review
+
+Reviewed on 2026-10-13 against the supplied Manus design/Laravel report and primary documentation. No real website or external runtime was executed in this research.
+
+| Recommendation | Treatment |
+| --- | --- |
+| Brief, tokens, components and browser acceptance | Implemented as distinct project documents and workflow responsibilities |
+| Blade + Tailwind + Alpine | Supported route; actual stack is verified and existing versions/components are preserved |
+| Bootstrap alternative | Supported route with Sass overrides before consuming imports and deliberate asset ownership |
+| A single UI skill | Separate visual, stack and review responsibilities; avoid conflicting visual systems |
+| daisyUI or own Blade components | Compatible layers: project Blade wrappers may use daisyUI |
+| Flowbite and Livewire/Flux | Conditional library guidance; no implicit installation or purchase |
+| Livewire assets and Alpine | Version/layout-aware; avoid a second Alpine copy and duplicate scripts |
+| Mandatory approval before every implementation | Material choices may need clarification; routine authorized work proceeds |
+| Ready custom skills/prompts linked by Manus | Their contents were not attached; supplied local wrappers and English examples are independently authored |
+| TypeUI reference-to-site workflow | References become a local design system, optionally imported/selected through TypeUI; code is built by the connected agent in the project |
+| SkillUI | Optional reviewed extraction, with executable-config/global-copy/data-destination boundaries; no default runtime integration |
+
+Primary sources:
+
+- [Tailwind Laravel guide](https://tailwindcss.com/docs/guides/laravel), [class detection](https://tailwindcss.com/docs/detecting-classes-in-source-files), [Blade](https://laravel.com/docs/blade), [Laravel Vite](https://laravel.com/docs/vite).
+- [Bootstrap Sass](https://getbootstrap.com/docs/5.3/customize/sass/), [Bootstrap Vite](https://getbootstrap.com/docs/5.3/getting-started/vite/), [Livewire installation](https://livewire.laravel.com/docs/installation), [Flux installation](https://fluxui.dev/docs/installation). Current Flux prerequisites are Laravel 10+, Livewire 3.7+ and Tailwind 4.2+; installed contracts direct agents to recheck actual versions.
+- [daisyUI Laravel fit](https://daisyui.com/laravel-component-library/), [official skill](https://github.com/saadeghi/daisyui/blob/master/skills/daisyui/SKILL.md): broad HTML/JSX invocation instructions are not adopted. [Flowbite Laravel setup](https://flowbite.com/docs/getting-started/laravel/): direct fetch was blocked, but the official indexed page exposed theme/plugin/source and JS setup; dynamic DOM behavior is not established by that example.
+- [Anthropic frontend-design](https://github.com/anthropics/claude-code/blob/main/plugins/frontend-design/skills/frontend-design/SKILL.md): useful visual method, below the brief. [Vercel web-design-guidelines](https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines): a wrapper can fetch mutable guidelines separately, so pinning the wrapper is insufficient.
+- [TypeUI overview](https://www.typeui.sh/docs), [MCP](https://www.typeui.sh/docs/overview/mcp-server), [design systems](https://www.typeui.sh/docs/creative/design-systems): themes, Markdown ZIP and Figma imports; authenticated HTTP MCP at `https://mcp.typeui.sh/mcp`. Workspace publishing/selection and saved package identity are distinct from code generation and hosting. No arbitrary URL-list import or Laravel code export was established.
+- [SkillUI](https://github.com/amaancoderx/npxskillui) inspected at `bc913a8d3503d6b2a683e4a3ac04ffe7304ac510`: [component scanner](https://github.com/amaancoderx/npxskillui/blob/bc913a8d3503d6b2a683e4a3ac04ffe7304ac510/src/extractors/components.ts) omits Blade/PHP; [Tailwind loader](https://github.com/amaancoderx/npxskillui/blob/bc913a8d3503d6b2a683e4a3ac04ffe7304ac510/src/extractors/tokens/tailwind.ts) invokes `jiti(configPath)`; [screenshot helper](https://github.com/amaancoderx/npxskillui/blob/bc913a8d3503d6b2a683e4a3ac04ffe7304ac510/src/screenshot.ts) uses Microlink; [CLI](https://github.com/amaancoderx/npxskillui/blob/bc913a8d3503d6b2a683e4a3ac04ffe7304ac510/src/cli.ts) can copy generated skills globally. The README's fixed npm 1.3.4 example is not a verified npm-to-Git integrity mapping and is not executed by AI-KIT.
+- [Playwright screenshot comparisons](https://playwright.dev/docs/test-snapshots): relevant browser/OS/font/data/animation controls for actual project regression tests.
+
+## Verification
+
+Verified on 2026-10-13, Windows/Python 3.12.14, using disposable fixtures outside the checkout:
+
+- Full discovery: 304 tests in 976.969 seconds; 300 passed, four skipped. Skips were POSIX hook execution, symlink creation privilege and two junction fixtures. Simulated linked/blocked path checks passed separately; unavailable native cases are not counted as passed.
+- Focused checks: ten Web Design tests and 24 checker tests passed. Covered whole-module default/preset absence, offline apply without process/network calls, independent persistence, source/native copies, preserved existing design documents, local/source conflicts, explicit retirement, disabled selection, blocked/linked paths and read-only scoped context for plain HTML and declared Laravel modules.
+- Kit validation: zero errors and zero warnings, including actual Git visibility. Before release labeling, the root README was 69664 UTF-8 bytes with no size quota; other instruction budgets remain scoped. The checker regression enlarges README without a size warning while retaining conditional-guide warnings and normal validation.
+- All 11 client selections in private/team fixtures: installed links, actual Git ignore visibility and unchanged reruns passed. Raw design output stayed ignored; ordinary design documents stayed visible.
+- Upgrade from tracked pre-change HEAD at version 1.2.0: project context/facts, preexisting design documents and native MCP configuration retained their bytes. Settings values/unknown preferences and both security package identities were preserved; reapplying stayed stable. This is a local reference-upgrade fixture, not a reconstruction of a published release. Manifest newline representations can differ between archive and checkout; identity comparison used parsed data.
+- Actual `doctor --fix` restored a missing design acceptance document without replacing the other design documents. Existing Context7/OpenRouter and following README sections stayed unchanged; archived v0.6.4 release text was preserved exactly apart from relative link relocation.
+- Four new skills passed the bundled skill-creator validator in Ubuntu/WSL with PyYAML. Python 3.10 grammar checks passed for CLI/scripts/tests; this does not establish execution under Python 3.10.
+- Offline wheel built in an isolated source copy and installed in a fresh venv. Smoke checks passed default installation, all four optional integrations, native entries, health checks, Web Design context selection and stable rerun. Final documentation is included in the rebuilt package; no packaging output was created in the source checkout.
+- Self-review covered ownership, defaults, module selection, file preservation/conflicts, path guards, visibility, registry/links, client copies, upgrade behavior and tool execution boundaries. This was not an independent agent review.
+
+Live TypeUI retrieval/publishing, SkillUI execution, actual client discovery, generated website acceptance and Laravel/browser application trials are unverified. Integration checks establish file/workflow contracts only; they establish no design quality, speed, cost or token savings.
+
+## Release labeling
+
+v1.3.0 is locally prepared on 2026-10-13. The full 304-test discovery above preceded labeling; labeling changes VERSION and maintainer release metadata without changing module behavior. Publication/tagging remain separate.
+
+Post-label verification on Windows/Python 3.12.14:
+
+- Eight CLI tests passed; the CLI module version, VERSION and parsed wheel metadata agree at 1.3.0. Kit validation returned zero errors/warnings.
+- The v1.3.0 wheel passed offline fresh-venv smoke: default installation, all four optional integrations, source/native skills, doctor, Web Design context and a stable rerun.
+- Upgrade from the pre-label 1.2.0 reference copy preserved project facts, settings values/unknown preferences, modified design documents, a locally edited Web Design skill, native MCP configuration and both security manifests byte-for-byte. Installed VERSION/state advanced to 1.3.0 without conflicts; doctor/links and repeat installation passed. This baseline already contained Web Design and is separate from the earlier tracked pre-change upgrade.
+- Final release documentation is included in the rebuilt wheel. These checks establish labeling/package preservation, not a new application or hosted CI result.

aikit/docs/WINDOWS_CI_FIX.md

@@ -0,0 +1,39 @@
+# Windows CI temporary-path regression
+
+Date: 2026-10-08. Bundle: 0.2.2. Scope: reference test fixtures.
+
+## Published evidence
+
+The supplied Windows/Python 3.13.15 log executed 45 tests and reported two failures:
+
+- Junction setup compared a path containing RUNNER~1 with a resolved parent containing runneradmin. The lexical containment check raised ValueError before creating the junction.
+- Rollback fault injection compared an unresolved fixture path with the installer's resolved destination. The equality condition did not match, so the intended OSError was never injected.
+
+Published main was read at 5b487824e3c6f5ab697981f4f3b19f59f5d16af4. Its tests/test_install.py matched the local pre-fix source after normalizing line endings.
+GitHub's [run 37819777582](https://github.com/tigusigalpa/ai-kit/actions/runs/37819777582) reported failure for Windows/Python 3.10 and 3.13, and success for Ubuntu/Python 3.10 and 3.13. The supplied Python 3.13.15 traceback and the separately read Windows/Python 3.10.11 job log show the same two failure signatures.
+No releases or tag refs were returned at this source check. The user has published the v0.2.2 source; this additional fixture fix remains local.
+
+## Correction
+
+The fixture now resolves the temporary root before deriving target/source paths:
+
+~~~python
+self.base = Path(self.temp.name).resolve()
+~~~
+
+The installer already resolves its target. Matching the fixture's path representation restores the intended containment checks and fault injection.
+Installer code, linked-path refusal, rollback logic, test assertions, and workflow gates were preserved. VERSION remains 0.2.2 while this release is being prepared.
+
+Two regression variants execute the existing rollback and junction scenarios under a real noncanonical temporary path. A sibling route with '..' gives the same directory a different lexical prefix without depending on NTFS short-name configuration. Cleanup is bound to the original TemporaryDirectory objects, never to the alias route.
+Before the correction, an independent reproduction produced the same ValueError and missing-OSError assertion signatures. After correction, rollback succeeds and junction setup reaches the actual host permission check.
+
+## Verification
+
+- Full local suite on Windows/Python 3.12.14: 47 tests, 44 passed, 3 skipped. Both rollback scenarios passed. The skips were symlink creation and the original/noncanonical junction variants due to host permissions.
+- Kit validation returned no errors/warnings, including Git visibility. Source inventory, ZIP bytes/integrity, and Python 3.10 syntax were verified for the repackaged bundle.
+- The independent reproduction now passes the rollback check and reaches the unavailable junction creation check. These equivalent-path scenarios exercise the path-spelling contract without claiming a successful local Windows 8.3 alias or actual junction trial.
+
+The [implementation record](IMPLEMENTATION.md#windows-ci-fixture-verification) indexes these results.
+Local junction creation remains unavailable in the sandbox; that check is reported as skipped, not passed. Successful hosted execution of the corrected Windows jobs requires publishing the fix and rerunning CI.
+
+No commit, push, tag, release, or remote repository write was performed.

aikit/docs/adr/0000-template.md

@@ -0,0 +1,24 @@
+# ADR-NNNN: Short title
+
+- Date: YYYY-MM-DD
+- Status: proposed / accepted / superseded
+
+## Context
+
+What verified problem are we solving, and which constraints matter?
+
+## Options
+
+Briefly list actual alternatives, including leaving things unchanged when possible.
+
+## Decision
+
+What was chosen and why?
+
+## Consequences
+
+What becomes simpler, and which new costs, risks, and rollback paths arise?
+
+## Verification
+
+How will we know the decision works? Link to code, tests, and documentation.

aikit/docs/adr/0001-adaptive-model-routing.md

@@ -0,0 +1,30 @@
+# ADR-0001: Adaptive routing by total cost to a correct result
+
+- Date: 2026-10-05
+- Status: accepted AI-KIT baseline policy
+- Source: the user's supplied "AI-KIT Adaptive Model Router" request.
+- Scope: kit instructions; no project stack, account access, or executable router is assumed.
+
+## Context
+
+The earlier kit preferred Terra for routine implementation and Sol for complex work. The new user policy specifies Luna, Sol 6.1, and exceptional Astra escalation. Cheap failed attempts, unnecessary reviewers, and duplicated context can increase total cost even when each call is inexpensive.
+
+## Options
+
+- Retain the previous fixed role mapping.
+- Route every task through the cheapest model or use the most capable configuration universally.
+- Choose model, reasoning, service tier, context, and review by task needs and verified runtime capabilities.
+
+## Decision
+
+Adopt the [adaptive router](../../template/ai-kit/router/POLICY.md) as the canonical policy: Luna for bounded work, Sol 6.1 medium for normal engineering, higher effort for demonstrated complexity, and Astra when a plausible capability improvement justifies cost. Diagnose failures before escalation. Use independent service-tier choices, targeted context, supported caching, suitable output budgets, and conditional review/delegation.
+
+## Consequences
+
+The kit can evolve as runtime capabilities and representative outcomes change. It requires truthful capability snapshots and actual verification. Markdown rules provide decisions; automatic switching needs a separate supported integration. New production-critical model choices require evaluation. Explicit user model/budget choices remain authoritative.
+
+If routing underperforms, adjust defaults using observed quality, retries, total cost, and latency; record the reason and synchronize the context, skill, and changelog. Avoid reverting solely on per-call prices.
+
+## Verification
+
+Check linked instructions, JSON decision examples, skill/context consistency, and absence of outdated active routing defaults. During project use, verify executed controls and outcomes separately; no live routing benchmark or API execution is claimed by this kit update.

aikit/docs/adr/0002-template-separation.md

@@ -0,0 +1,24 @@
+# ADR-0002: Clean templates and conservative upgrades
+
+- Date: 2026-10-08
+- Status: accepted for the local working distribution
+
+## Context
+
+Three external reviews corroborated duplicated operative policy, mixed kit/project history, ambiguous ignore installation, and missing shipped checks.
+
+## Decision
+
+Keep canonical installable instructions in template/, maintain kit facts/history at the root, and route conditional rules through short entries.
+Use private/team ignore templates and a cross-platform standard-library installer. Preview by default; preserve project-owned files and local managed-file adaptations.
+Update managed files only from a known unchanged baseline. Conflicts require review; no blind folder replacement or force flag.
+Keep owner conventions as this user's default; expose explicit settings for other installations.
+
+## Consequences
+
+The installer handles mechanics; bootstrap still verifies and reconciles project semantics. Baselines/candidates are local private state.
+Plain instructions do not guarantee client activation, model switching, or command enforcement. Test those controls in the actual runtime.
+
+## Verification
+
+Behavioral tests cover dry-run, repeat installation, upgrade conflicts, scoped ignores, and path boundaries. [Results](../IMPLEMENTATION.md#verification).

aikit/docs/adr/0003-agent-registry-and-router.md

@@ -0,0 +1,24 @@
+# ADR-0003: Data-driven agent registry and offline router helper
+
+- Date: 2026-10-10
+- Status: accepted for the local working distribution
+
+## Context
+
+Agent wiring was hardcoded in the installer as three parallel constants (entry files, valid names, optional integration files), so adding a client meant editing installer code. The router was pure policy: provider JSON declared model roles, but nothing turned that into a concrete recommendation or a generated configuration, and there was no place to record which providers a project actually had.
+
+## Decision
+
+Move the client list and each adapter's entry files into [integrations/agents.json](../../integrations/agents.json), a single registry shared by the installer and the checker. Derive agent names, gated template entries, optional integration files, and Claude skill copies from that registry.
+
+Add [scripts/router.py](../../scripts/router.py), an offline, standard-library helper with two commands: `route` returns a deterministic capability recommendation (level/role/effort plus a resolved provider/model), and `configure` writes a resolved role mapping and a native Aider model file. Record provider availability and role overrides in [selection.json](../../template/ai-kit/router/selection.json).
+
+Keep the distribution offline and credential-free; classify with transparent keyword rules and skip unverified or self-hosted-supplied models rather than inventing model IDs.
+
+## Consequences
+
+Adding a client is a data change, not installer code; the checker validates the registry against template entries and integration sources. `route`/`configure` respect the existing "no switching runtime" boundary: they advise and generate, never switch or store credentials.
+
+## Verification
+
+Router, registry, and provider-schema regressions run alongside the installer/checker/doctor suites. [Results](../IMPLEMENTATION.md#verification).

aikit/docs/adr/0004-onboarding-and-project-facts.md

@@ -0,0 +1,24 @@
+# ADR-0004: Interactive onboarding and machine-readable project facts
+
+- Date: 2026-10-10
+- Status: accepted for the local working distribution
+
+## Context
+
+Installation required composing a flag list by hand, and the installer only detected that a stack profile was present — not the language version or the project's test/lint/build commands. The `PROJECT_CONTEXT.md` module map therefore stayed mostly `not established` until a human filled it in.
+
+## Decision
+
+Add `--interactive` to prompt for mode, language, conventions, agents, and extras, and `--check` to run the project doctor immediately after a successful `--apply`. Add a `Makefile` front-door wrapping the common commands.
+
+Add a schema-versioned `ai-kit/project.json` and detect, per module, the manifests, language, version, and suggested commands from go.mod, pyproject.toml, package.json, and composer.json. Draft both `PROJECT_CONTEXT.md` and `project.json` from that evidence on a fresh install, marked as suggested until bootstrap confirms them; preserve existing project facts.
+
+Add `scripts/adr.py new` and `scripts/changelog.py add` to lower the cost of the document step.
+
+## Consequences
+
+Detected versions and commands are drafts, never verified facts, and existing context/history stays untouched. A `Makefile` is a convenience over the canonical Python commands, not a replacement for them.
+
+## Verification
+
+Onboarding, detection, project.json, and helper regressions run with the installer/checker/doctor suites. [Results](../IMPLEMENTATION.md#verification).

aikit/docs/adr/0005-client-settings-ownership.md

@@ -0,0 +1,30 @@
+# ADR-0005: Key-level client settings ownership and confirmation guards
+
+- Date: 2026-10-10
+- Status: accepted for the local working distribution
+
+## Context
+
+The session-start and guards extras generated .claude/settings.json as one installer-managed file. Any existing project settings file became a conflict, and later user edits looked like local adaptations. The guards denied Git commit/push, although Core allows these operations on an explicit user request, so an authorized commit was blocked. The session-start hook printed an instruction to read PROJECT_CONTEXT through a relative cat command, costing an extra read every session.
+
+## Options
+
+- Keep whole-file ownership and ask users to merge candidates by hand.
+- Own a marked block, as in .gitignore; JSON has no comments, so a block cannot be delimited.
+- Own individual entries: listed permission rules and hook groups identified by their command.
+
+## Decision
+
+Own individual entries and record them in installer state under managed_json. Each run removes stale owned entries, adds missing ones, and preserves all other content; a file that is not a JSON object becomes a reviewed conflict with the AI-KIT fragment as candidate. Earlier whole-file installations migrate on the next run.
+
+Guards use permissions.ask for Git commit/push. The session-start hook runs a managed script via $CLAUDE_PROJECT_DIR, piped through tr so CRLF checkouts still run, and prints the instructions, current PROJECT_CONTEXT (capped), and Git status.
+
+The preview also reports clients detected from existing native files, declared as detect markers in the agent registry, without changing the selection.
+
+## Consequences
+
+Existing client settings survive installation and upgrades; the file is reformatted as two-space JSON only when an owned entry changes, after a backup. Guards now need user confirmation rather than blocking, which matches Core but is weaker against unattended runs. The hook depends on POSIX sh, tr, and head in the client's hook shell.
+
+## Verification
+
+Merge, migration, conflict, disable, doctor, detection, and hook-execution regressions run with the installer suites. [Results](../IMPLEMENTATION.md#client-settings-and-detection-verification).

aikit/docs/adr/0006-routing-evidence-and-local-measurements.md

@@ -0,0 +1,26 @@
+# ADR-0006: Evidence-based recommendations and optional local measurements
+
+- Date: 2026-10-10
+- Status: accepted for the local working distribution
+
+## Context
+
+The offline classifier diverged from the canonical capability ladder, matched fragments inside unrelated words/file names, and ignored explicit selection effort. Russian task descriptions fell through to the engineering default. There was no local accounting contract to test whether instruction/context or routing changes improved cost to a correct result. Filament work depended on a broad Laravel wrapper despite distinct UI/version/authorization concerns.
+
+## Decision
+
+Keep the capability ladder in [POLICY](../../template/ai-kit/router/POLICY.md); regression tests compare its table with the implementation mapping. Classify English/Russian operations with bounded patterns and explicit risk/component evidence, retaining manual overrides. Expose signals, requested effort, declared controls, and unresolved models separately. Level 6 requires explicit diagnosis; recommendations do not execute tasks or switch clients. Arbitrary model IDs do not inherit another model's effort capabilities.
+
+Add a conditional Filament profile/skill and suggest it from known Composer dependencies, including component-only installs and lock evidence. Actual versions and use remain bootstrap facts. Keep personal conventions in OWNER and retain the existing minimum-context/module-map procedure.
+
+Measure only on request through a local schema and journal. Store opaque IDs and actual executed settings, nullable telemetry, reviewed outcomes, all attempts, rework, and escalation. Ignore runtime journals in both sharing modes; never install a populated journal or overwrite it on upgrades. Costs include unsuccessful work; incomplete coverage or mixed currency leaves cost per correct result unknown.
+
+Use a [fixed-model real-project protocol](../EVALUATION.md) to evaluate instructions first and routing separately. Real-project trials are deferred by the owner's choice. Multi-agent orchestration remains deferred until measured benefit and explicit authorization justify it.
+
+## Consequences
+
+Rules remain conservative heuristics and can over/under-route; explicit evidence and review are necessary. Unknown custom/local capability controls stay null until configured. Journaling is manual and opt-in, so coverage depends on runtime evidence supplied by the evaluator. The helper protects cooperating writers with an exclusive lock; interrupted locks require manual investigation. These choices add no network dependencies or always-loaded provider/profile context.
+
+## Verification
+
+Tests cover policy consistency, multilingual/risk regressions, effort support/precedence, scoped dependency suggestions, preservation/skill upgrades, measurement accounting/validation, and boundary guards. The kit checker verifies links, registries, template isolation, and private/team visibility. [Release verification](../V0_5_0.md) records actual results and unavailable checks.

aikit/docs/adr/0007-generated-client-configuration-and-presets.md

@@ -0,0 +1,34 @@
+# ADR-0007: Generated client configuration, scoped module rules, presets, and workflow skills
+
+- Date: 2026-10-10
+- Status: accepted for the local working distribution
+
+## Context
+
+After installation, agents still had to remember to open the right stack profile, asked permission for every routine check, could read secret files, and depended on a pasted bootstrap prompt. The installer already knew module paths, profiles, and commands (project.json) and owned entries in client settings (ADR 0005), but turned none of it into native client configuration. Optional machinery needed several flags to assemble.
+
+## Options
+
+- Keep instructions only and document manual client setup.
+- Generate one always-on rule per client listing all modules.
+- Generate per-module native configuration from project.json through each client's documented mechanism, opt-in, with presets for common combinations.
+
+## Decision
+
+Generate opt-in configuration from project.json (falling back to detection):
+
+- native-settings: Claude Code allow rules for recorded single-command checks, Read deny rules for secrets from one gitignore-style list plus detected stacks, and a marked secret block in Cursor, Aider, and Gemini ignore files. Private mode writes the personal .claude/settings.local.json; team mode writes the shared .claude/settings.json; owned entries move with the mode.
+- scoped-rules: one managed rule per module with stack profiles for Claude Code (paths), Cursor (globs), Copilot (applyTo), Windsurf (trigger glob), and Cline (paths); the root module uses each client's always-on form.
+- data-guards: ask rules before destructive file, Git, Docker, and detected migration commands.
+- Presets minimal, solo, team, and strict set the managed extras and optionally the mode; explicit flags win and the preview names extras a preset turns off.
+- Portable user-invoked workflow skills: ai-kit-bootstrap, ai-kit-review, and ai-kit-sync-context.
+
+Codex receives no nested AGENTS.md, because it reads AGENTS.md only from the repository root to its working directory, and no config.toml, because approval and sandbox choices belong to the user. Skills use only name and description so Codex and Gemini read the same files; Claude-only invocation fields are not added.
+
+## Consequences
+
+Routine checks stop prompting in Claude Code, secret reads are refused by supporting clients, and module profiles attach where those files are touched. Generated files and entries follow project.json on the next installer run; edited generated rules become conflicts. Prefix permission rules and ignore files are not security boundaries: shell commands can still read files. Disabling an extra removes owned settings entries and ignore blocks but leaves generated rule files for review.
+
+## Verification
+
+Regressions cover private/team settings files, mode switches, migration from shared to local entries, unsafe commands, project.json precedence, ignore blocks, data guards, every rule format, root modules, path skipping, slug collisions, retirement, presets, the CLI, and workflow skills. [Results](../V0_6_4.md).

aikit/docs/adr/0008-unified-cli-and-fact-drift.md

@@ -0,0 +1,20 @@
+# ADR-0008: Unified CLI, fact-drift detection, and non-Latin chat languages
+
+- Date: 2026-10-10
+- Status: accepted for the local working distribution
+
+## Context
+
+The distribution ships several standalone scripts (`install.py`, `doctor.py`, `router.py`, `metrics.py`, `adr.py`, `changelog.py`, `check_kit.py`, `docker_test_usage.py`), so the entry surface is a Makefile plus individual `python scripts/...` calls. `PROJECT_CONTEXT.md` and `ai-kit/project.json` hold the same facts in prose and machine-readable form, and nothing checked that they stayed in agreement. `chat_language` accepted only Latin names despite the promise of chat in any language.
+
+## Decision
+
+Add a thin `aikit` dispatcher (`aikit_cli.py`) plus a `pyproject.toml` console script, deriving its version from VERSION; each subcommand forwards to the existing script. Add a doctor check that the module paths in `project.json` and `PROJECT_CONTEXT.md` agree. Relax `chat_language` to any nonempty, control-character-free name up to 60 characters.
+
+## Consequences
+
+The scripts keep their own entry points; the dispatcher is a convenience, not a replacement. A portable wheel install still needs package-data packaging, which stays deferred. Fact drift becomes a doctor warning rather than silent divergence.
+
+## Verification
+
+Covered by the installer/doctor/aikit regressions. [Results](../IMPLEMENTATION.md#verification).

aikit/docs/adr/0009-provider-review-doctor-fix-and-ci-self-install.md

@@ -0,0 +1,20 @@
+# ADR-0009: Provider review listing, doctor --fix, and CI self-install
+
+- Date: 2026-10-10
+- Status: accepted for the local working distribution
+
+## Context
+
+Provider verification state lived only inside per-provider JSON, so a pending or stale mapping was easy to miss. The doctor reported missing managed files but offered no way to restore them. The CI extra required installer state in Git, which private mode deliberately excludes.
+
+## Decision
+
+Add `router.py providers` to surface tier, verification status, date, and primary-doc sources for every provider. Add `doctor.py --fix` to re-run the installer and restore missing managed files and owned documents while preserving local edits and reporting conflicts. Make the CI extra install AI-KIT itself from a reviewed revision when state is absent. Add a golden snapshot test pinning the generated Claude settings merge.
+
+## Consequences
+
+Provider verification becomes a visible review task rather than hidden JSON; Gemini remains pending until verified. `--fix` is conservative: it never overwrites local edits. The CI extra now needs network access to clone the kit and must pin a reviewed revision.
+
+## Verification
+
+Covered by router, doctor, native-settings, and aikit regressions. [Results](../IMPLEMENTATION.md#verification).

aikit/docs/adr/0010-metrics-analysis-and-gemini-verification.md

@@ -0,0 +1,20 @@
+# ADR-0010: Measurement analysis for routing and Gemini verification
+
+- Date: 2026-10-10
+- Status: accepted for the local working distribution
+
+## Context
+
+Local measurements aggregated only by experiment/arm, so the per-provider evidence needed to tune `ai-kit/router/selection.json` had to be assembled by hand. The Gemini provider remained a pending scaffold, so route/configure could not resolve a Gemini model.
+
+## Decision
+
+Add `metrics.py analyze` to aggregate reviewed tasks per provider (attempts, success rate, cost coverage, cost per correct result, models/efforts). It is descriptive and read-only: it informs `selection.json` but never rewrites it. Verify the Gemini cheap/work/escalation model IDs against current primary documentation and record them in `gemini.json`; keep effort unknown until Gemini's thinking levels are confirmed.
+
+## Consequences
+
+Routing feedback stays evidence-based and conservative, with no auto-mutation or price lookup. Gemini now resolves real model IDs, but its reasoning effort remains an unknown rather than a fabricated control.
+
+## Verification
+
+Covered by metrics, router, and checker regressions. [Results](../IMPLEMENTATION.md#verification).

aikit/docs/adr/0011-evidence-lifecycle-and-evaluation.md

@@ -0,0 +1,20 @@
+# ADR-0011: Evidence freshness, adapter lifecycle, and evaluation coverage
+
+- Date: 2026-10-10
+- Status: accepted for the local working distribution
+
+## Context
+
+Provider-level analysis could collapse matching task IDs from different experiment arms, adapter retirement required manual deletion, and project context had no durable evidence that its manifest facts were still current. Client adapter documentation status was scattered across prose. The evaluation protocol needed a minimal private pairing tool, while indirect prompt injection and tool-server scope required a concrete policy boundary. Finally, the console script was editable-install-only rather than verified as a portable wheel.
+
+## Decision
+
+Release v0.10.0 with backward-readable measurement schema 2, adding per-attempt disposition and experiment/arm/task identity to provider analysis. Capture manifest digests in optional project-fact evidence and have doctor report module, profile, and evidence drift; `aikit context snapshot` is preview-first and updates evidence only on explicit apply. Add `aikit adapters report` and a conservative explicit `retire` flow that backs up and removes only unchanged tracked adapter files. Add client documentation metadata to the registry, a private opaque A/B task-pack scaffold/coverage harness, and an MCP posture policy. Package repository resources with the `aikit` console script and add cross-platform wheel smoke jobs.
+
+## Consequences
+
+Existing schema 1 metric journals remain valid but have unknown attempt disposition. Context snapshots are evidence of reviewed manifests, not automatic truth or command execution. Retirement never deletes local edits, untracked files, directories, client settings fragments, or ignore blocks. Client documentation verification remains distinct from native client activation. The evaluator reports record completeness, not semantic correctness or causal performance. Wheel and hosted CI behavior remain unverified until the workflow runs on a published revision.
+
+## Verification
+
+Covered by new metrics, context, adapter, evaluator, package, checker, and CLI regressions; final local and hosted execution results must be recorded separately.

aikit/docs/adr/0012-measurement-led-routing.md

@@ -0,0 +1,31 @@
+# ADR 0012: Measurement-led routing and isolated benchmarks
+
+Status: accepted for local tooling; live client adapters and orchestration remain deferred.
+
+## Context
+
+The local distribution already has an offline router, conservative installer, optional telemetry journal, manifest snapshots and opaque A/B coverage. Neither keywords nor generated configuration establish actual execution or savings. The owner requested code/tests now and real application trials separately.
+
+## Decision
+
+Build on the existing contracts. Add backward-readable metric schema 3 with explicit case/repetition/revision/stack/class/level/capabilities and semantic-review metadata. Preserve schemas 1/2. Estimated prices remain labeled subtotals and cannot become actual cost per correct result or savings.
+
+The benchmark reads Git blobs at an exact commit, without checkout filters, hooks, history, hardlinks or source mutations. Each task/arm/repetition gets a new directory. A uses no installed kit; B uses the kit with A's exact provider/model/effort pin; C requests an adaptive recommendation. Reject tracked secret/runtime paths, links, submodules and preinstalled kit trees. Rotate arm order between repetitions. Preserve interrupted runs for inspection; do not automatically delete them or retry paid work.
+
+Execution requires an owner-reviewed `aikit-worker-v1` subprocess that accepts a JSON request on stdin and returns actual attempt telemetry on stdout. The harness controls working directory, timeout and a minimal environment; this is process separation, not a security sandbox. It does not ship an unverified vendor API/client switch. Requested controls and reported execution stay separate. An actual client adapter needs primary documentation verification, credential handling outside reports, and integration tests before being recommended for live use.
+
+Automated checks do not set semantic correctness. Explicit manual/independent review changes outcomes with backups. Reviewed records export idempotently into the existing private journal. Comparisons require matched starting states/tasks and real single-currency costs, include failed/recovery work, and block savings when correctness falls below baseline. Fixed-model comparisons additionally require identical observed model/effort. Report observed differences, never predictive guarantees or causation.
+
+Optional routing modes/profiles/pins live in a separate configuration. Existing selection files/defaults remain valid. Adaptive recommendations require sufficient distinct immutable cases, comparable trial sets, complete actual costs, a conservative quality lower bound and quality no worse than the incumbent. Balanced also requires measured speed no worse. Mixed-model strategies remain in cost summaries but cannot be attributed to a single model for learning. Pins and explicit controls override recommendations. Proposal history stores evidence fingerprints and prior selection; restore is explicit, preview-first, guarded and backed up. No proposal changes active configuration.
+
+Context selection is read-only, by declared module scope and profiles. Keep Core, settings, engineering/security, project facts, relevant profiles, applicable nested instructions and architectural decisions even when they exceed the measured byte budget. Detect byte-identical duplicates and flag unknown module scope. Do not infer loaded tokens from selected bytes or treat manifest drafts as verified stack use.
+
+## Orchestration research
+
+Configurable planner/executor/reviewer/escalation roles map to existing selection roles rather than model names. Recommended starting mappings use work/work/work/escalation; a project can select cheap planning or review only after evidence. These mappings are configuration for a future adapter, not executed calls.
+
+A live orchestrator must: verify supported switching; isolate credentials and disposable services; account for every planning/review/delegation/recovery call; bind outcomes to task identity; preserve useful outputs across escalation; and stop when the measured coordination cost exceeds the benefit. Compare it against the fixed kit arm on matched tasks, require no quality regression, and include coordination spend in cost per correct result. No automatic Git operations or routing-policy writes. This phase follows real benchmark evidence rather than preceding it.
+
+## Consequences
+
+The kit is useful without switching: context selection, explicit pins, manual telemetry and conservative analysis all work offline. Synthetic workers establish harness behavior only. Historical samples and Wilson bounds are decision aids with correlated-task and distribution-shift limits; representative held-out application trials remain necessary. No savings or native client activation has been established by this implementation.

aikit/docs/adr/0013-docker-cli-image.md

@@ -0,0 +1,24 @@
+# ADR 0013: Standalone Docker CLI image
+
+- Date: 2026-10-14
+- Status: accepted for local integration; registry and cluster deployment remain separate.
+
+## Context
+
+The owner requested a Docker image for the portable instruction/installer kit. The existing Python CLI already supports preview, explicit apply, preservation, conflict candidates and scoped helpers. Its workload is a command that finishes; no server, agent loop or model adapter is required.
+
+## Decision
+
+Package the existing no-runtime-dependency wheel in a multi-stage Linux image. Pin the Python base by digest and build tools by wheel hashes. Require the source VERSION to match the OCI label; resolve Debian Git packages at build time and record actual runtime versions. The runtime starts offline without installing packages or mounting source code.
+
+Run as UID/GID 10001:10001, with exec-form `aikit`, writable temporary storage and an explicitly mounted application. Support an alternate non-root UID for host ownership. Preview uses a read-only project mount; writes retain the installer's explicit apply/conflict contract. Preserve installer defaults and canonical template policies. Ship no Docker socket, credentials, scanner runtime, HTTP server or model worker.
+
+Use a Kubernetes Job for an optional installation preview. Its exit status is the health/completion contract: no Service or artificial probes. Disable automatic retries, API-token mounting and privilege escalation; allocate temporary storage separately from the existing project PVC. Resource values are estimates. Apply operations and actual cluster deployment require a separately reviewed configuration.
+
+SIGTERM stops the foreground CLI. This does not promise a transactional rollback during installation; after interrupted writes, inspect, run doctor and preview again. Add no launcher that changes host ownership or globally trusts Git directories. A shared builder does not establish test-cache ownership and cannot justify pruning.
+
+## Consequences and verification
+
+Users can run the installer without host Python; native client activation and external toolchains remain separate. Builds need network access and regular base/tool review. Git package resolution means rebuild bytes can differ; distribution requires a reviewed final image identity and explicit publication authorization.
+
+The [README](../../README.md#run-ai-kit-with-docker) documents usage. [Docker verification](../DOCKER.md#verification-results) records actual builds, offline/non-root/read-only behavior, all extras, preservation, reruns, signals, wheel resources, full regressions and schema coverage. Synthetic tests do not establish application, hosted CI or cluster acceptance.