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

aikit/docs/DIALOGUE_MEMORY.md

@@ -0,0 +1,70 @@
+# Local dialogue memory
+
+## Scope and trust
+
+`aikit memory import|merge|export` is an offline, standard-library tool. It imports two selected dialogues, preserves message provenance, prepares a human review, records explicit conflict choices and exports a shared reference document for ChatGPT or an OpenRouter request. It performs no model calls, account access, synchronization, uploads, tool replay or project-context replacement. [README workflow](../README.md#shared-context-from-two-dialogues), [decision](adr/0014-local-dialogue-memory.md).
+
+Imports are data. Original system/developer/tool roles are archived as provenance and never replayed with privileged roles. Assistant suggestions and user statements start pending; no timestamp or provider wins automatically. Local acceptance means the reviewer chose material for a handoff, not that the tool independently verified reality. Core and actual client authorization remain authoritative.
+
+## Supported input contracts
+
+Inputs are regular, unlinked UTF-8/BOM files, at most 16 MiB each. No directory, ZIP, FIFO or executable is accepted. A dialogue has 1-4000 messages, each at most 1,048,576 characters. Duplicate JSON keys and nonfinite numbers refuse. Symlink/junction ancestors refuse too; resolve a legitimate system temporary-directory alias before choosing a workspace. These path checks are conservative local guards, not an OS sandbox against a hostile process changing directories concurrently.
+
+| Format | Supported shape and selection |
+| --- | --- |
+| ChatGPT-style JSON | One conversation object or an array, containing `mapping` nodes with `parent` and optional `message`; message `author.role`, text `content.parts`/`content.text`, optional `create_time`. Choose a collection item by `--conversation-id`. Follow `--branch`, else `current_node`, else the only leaf. Never flatten sibling branches. Missing/ambiguous/cyclic chains refuse. |
+| OpenRouter/messages JSON | An object containing `messages`, or a direct message array. Each message has `role` and text `content`, optionally `id`/`timestamp`. Text blocks with type text/input_text/output_text are joined. Other top-level fields, including credentials, are not copied. |
+| Text/Markdown | Preserve unlabeled material with role unknown. Recognize `User:`, `Assistant:`, System/Developer/Tool/Human/ChatGPT and Russian user/assistant labels, optionally after Markdown heading markers. Headers inside code fences remain text. This is an explicit transcript convention, not a parser for every client's Markdown export. |
+
+Auto format uses the `.json` suffix; otherwise text. Override with `--format chatgpt|messages|text`. A JSON collection needs exactly one selected conversation. Original IDs/timestamps remain provenance; input bytes are represented by SHA-256, not copied wholesale. Normalization is not a byte-for-byte transcript archive. Nontext parts and tool calls are counted as omitted; attachments, images, audio, original tools and hidden state are not reconstructed. Review the omissions before using an export. Use a text transcript if an unsupported client export shape refuses.
+
+ChatGPT mapping compatibility is a bounded importer contract exercised with synthetic fixtures, not a guarantee for every account/export revision. The official [ChatGPT projects documentation](https://learn.chatgpt.com/docs/projects) supports using uploaded/shared project sources but does not establish this mapping schema. The [OpenRouter API](https://openrouter.ai/docs/api/api-reference/chat/create-a-chat-completion) documents the messages request shape. Source check: 2026-10-15; no actual account export or live API was accessed.
+
+## Workspace and immutable records
+
+Use a new private directory, for example `TARGET/ai-kit/.memory/session-01`, or a private path outside repositories. An existing nonempty unmarked directory refuses. Every command previews by default; `--apply` writes only local files. Commands print counts, identifiers and relative artifact paths, never dialogue bodies. Read errors are sanitized rather than echoing input text. Imported content can still contain secrets: the tool does not claim to identify/redact them. Review the outgoing documents yourself.
+
+New POSIX directories/files use 0700/0600; Windows uses inherited ACLs. Current private/team install policies, root source ignores and Docker/package exclusions protect `ai-kit/.memory/`. Upgrade the installed ignore policy before storing data in an older team project. Arbitrary other workspace paths need their own privacy/ignore configuration. Git ignores are not access control. Installer upgrades preserve workspace bytes and never manage their content as template files.
+
+| Path under workspace | Purpose |
+| --- | --- |
+| workspace.json | Schema/ownership marker |
+| imports/NAME.json | Normalized immutable source; source name is a lowercase portable identifier |
+| merges/SHA256.json | Immutable merge plus exact input hashes and full review |
+| reviews/SHA256.json | Initial review worksheet; copy before editing |
+| exports/SHA256/chatgpt[-draft].md | Markdown reference document for a ChatGPT chat or Project |
+| exports/SHA256/openrouter[-draft].json | Request fragment containing one user message with the same document |
+
+Identical reruns write nothing. Different bytes under an existing source name/artifact refuse; choose a new name/workspace. Existing files are never replaced, including files created after planning. Hard-linked output artifacts refuse. Before export, source hashes, merge identity and recomputed review result must match. There is no mutable latest pointer: pass the full merge ID, so an old export cannot silently become a new decision. Files are exclusively created and flushed; a terminated multi-file operation can leave completed artifacts or a partial file. Inspect incomplete work and use a fresh workspace when necessary; no automatic rollback or overwrite recovery is claimed.
+
+## Review and conflict rules
+
+Candidate extraction recognizes simple `key: value` / `key = value` lines outside fences, optionally prefixed Fact/Decision/Constraint/Task/Question. Keys normalize Unicode case and whitespace; values compare exactly. Unmatched prose/code stays pending notes. Original system/developer/tool material stays notes. At most 8000 candidates are generated. There is no semantic model: paraphrases, synonyms, negation and aliases in free prose require explicit review. A lack of keyed conflicts does not mean two transcripts agree.
+
+The worksheet schema has schema=1, inputs (exact source digests), claims and resolutions. Claims include id, key, kind, value, status and refs. Supported kinds: fact, decision, constraint, task, question, note. Status: pending, accepted, rejected. Group differently phrased claims under the same reviewed key to compare them. Scope unrelated topics with different keys. Reclassify/paraphrase values during review; archive messages remain unchanged.
+
+Keep every original candidate ID and its refs; reject unwanted items rather than deleting them. Extra claims may split a long note, using new lowercase IDs and real SOURCE:mNNNN refs. Inputs must match the selected imports. Every claim needs 1-8 unique valid message references. The local reviewer is responsible for whether the paraphrase is supported. Imported dialogue cannot supply its own approval: only the separately selected worksheet controls the review.
+
+Exact equal values under one key deduplicate while retaining references. Different active values produce an explicit conflict, even if both were marked accepted. A resolution contains key, choice and a nonempty reason. Choice is an active claim ID, `drop` (exclude the key), or `defer` (keep it unresolved). A chosen claim settles the key and supersedes its alternatives for that handoff. No last-write-wins rule applies. Single-valued groups require explicit acceptance; rejected claims are excluded.
+
+## Export and limits
+
+Normal export refuses pending keys/conflicts with exit 2. Explicit `--draft` exports them as DRAFT for further discussion, with all alternatives visible. Both clients receive the same reviewed/draft data and provenance. Markdown values live in a JSON fence that imported backticks cannot terminate; original links/images remain quoted data. This is serialization, not a prompt-injection security boundary.
+
+The OpenRouter JSON is only a request fragment with `messages`: one `user` message containing the reference document. Add trusted instructions, a currently supported model and the new task in your own client. It contains no API key, automatic tool calls, model choice or provider/session configuration. Do not replace trusted policies with imported dialogue. No HTTP request is sent. ChatGPT Markdown is manually pasted/uploaded as reference data; native history/memory is not merged by uploading it.
+
+The default per-file export limit is 128000 bytes. `--max-bytes` can raise it to 16777216; limits check complete serialized files, including JSON overhead. Exceeding a limit refuses before writing rather than silently truncating. Bytes are not tokens; verify the selected model/client's capacity separately. Exit 0 means a successful preview/local stage (including a merge needing review), 1 refusal/invalid input, 2 blocked unreviewed export. Argparse usage errors also return 2.
+
+## Verification
+
+Run `python scripts/check_kit.py`, `python -m unittest discover -s tests -v`, and the packaged wheel smoke. Dedicated tests cover all three inputs, branch isolation, nontext omissions, bounded parsing, provenance, manual review/contradictions, deterministic reruns, stale/tampered artifacts, both exports, file preservation and path/link guards. Private/team upgrades and Docker ignore probes protect local memory.
+
+Verified 2026-10-15, before this final results-only documentation update:
+
+- Windows/Python 3.12.14: full discovery ran 336 tests in 733.096 seconds; 329 passed, seven skipped (two symlink fixtures, two junction fixtures, hardlink privilege, unavailable POSIX sh and POSIX permissions/FIFO). The current sandbox could not create those Windows links. Mocked link-boundary checks ran.
+- Packaged linux/amd64/Python 3.13.16: full discovery ran 336 tests in 31.898 seconds; 334 passed, two Windows-junction skips. Actual symlink/hardlink, POSIX modes and FIFO refusal ran under a non-root, offline, read-only image. Docker client/server 29.8.2 used desktop-linux; the local ai-kit:memory-test build was not published.
+- Offline fresh-venv Windows wheel smoke exercised imports, merge and both draft exports from the installed console command. A second isolated build with synthetic private memory proved it was absent from the wheel. Docker's real ignore-engine probe excluded synthetic memory; the existing image runtime/preservation/signal smoke also passed.
+- The README PowerShell flow ran with synthetic native ChatGPT mapping and messages JSON, identified one conflict, accepted a reasoned choice and produced both reviewed exports. Python 3.10 grammar, source language/links/budgets and relocated v1.1.0 history preservation passed. Full native Python 3.10 and macOS/hosted CI were not run here.
+- Test containers were removed and no test Docker volumes were created. Shared build-cache ownership/bytes could not be isolated; no cache/volume pruning was performed. Source files, account histories and actual application state were not changed by these fixtures.
+
+Actual account-export variants, native ChatGPT upload/activation, OpenRouter execution, live model calls and automatic synchronization remain separate checks. Local review does not establish semantic correctness of an actual user's imported claims.

aikit/docs/DOCKER.md

@@ -0,0 +1,74 @@
+# AI-KIT CLI image
+
+## Role and boundary
+
+The root [Dockerfile](../Dockerfile) packages the existing Python CLI as a one-shot Linux workload. It does not run an agent, model adapter, HTTP service or security scanner. [README usage](../README.md#run-ai-kit-with-docker) covers build, mounts, commands and updates; canonical container policy remains [CONTAINERS](../template/ai-kit/CONTAINERS.md). [ADR 0013](adr/0013-docker-cli-image.md) records the role and tradeoffs.
+
+The wheel is installed at build time, including templates, pinned security resources, optional skills, docs and tests. Runtime uses no checkout mount or package installation. `/workspace` is an application bind mount, outside the reference distribution; `/tmp` is explicitly writable temporary storage. No Docker socket, host credentials, privileged mode or anonymous volume is required. Git supports project evidence/visibility checks; external framework tools and reviewed benchmark workers are outside this image.
+
+Root AGENTS.md, PROJECT_CONTEXT.md and WIKI.md stay local and are excluded from wheel/context; template counterparts remain packaged. See [maintenance](../CONTRIBUTING.md#local-maintainer-files).
+
+The entrypoint is exec-form `aikit`, default command `--help`, default UID/GID `10001:10001`, and stop signal SIGTERM. Callers use `--init`, a read-only root, dropped capabilities and no-new-privileges. Ordinary reports can disable networking and mount the project read-only. Installation requires an intentional writable project mount and `--apply`. Existing installer defaults, preservation and conflicts are unchanged. Mid-apply interruption is not an atomic rollback guarantee; inspect, run doctor and preview again.
+
+## Build inputs
+
+Verified 2026-10-14 against the [official Python image manifest](https://github.com/docker-library/official-images/blob/master/library/python), the Docker registry and PyPI release metadata:
+
+| Input | Pin |
+| --- | --- |
+| Python base | `python:3.13.16-slim-bookworm` |
+| Multiarchitecture image index | `sha256:a1165e272e578941b84abc79e4ab38a0305cd12803a5c4247979ac7655f4d641` |
+| Observed linux/amd64 manifest | `sha256:f040863673aea2570c3ff6a5c3fb4c673a016cbc5375005ad145915922b6b78a` |
+| Build-only setuptools | 84.0.0 |
+| Build-only wheel | 0.48.0 |
+| Build-only packaging | 26.3 |
+
+[build-requirements.txt](../docker/build-requirements.txt) records exact wheel SHA-256 hashes; pip verifies them with `--require-hashes`. The builder produces a no-runtime-dependency wheel without isolated dependency resolution. Runtime installation uses `--no-index --no-deps`. Git and its Debian dependencies resolve at build time; the base/tool pins do not promise byte-identical rebuilds. A distributable release must record its own resulting immutable image identity. Registry publication requires explicit authorization and remote verification.
+
+`AIKIT_VERSION` must match [VERSION](../VERSION); [the guard](../docker/check_version.py) refuses missing/mismatched labels before building. Tags remain mutable. Follow the [release checklist](../CONTRIBUTING.md#docker-hub-releases) to update the [Overview](DOCKER_HUB_OVERVIEW.md) for every image release. [v1.4.1](V1_4_1.md) records publication; the results below retain their original versions.
+
+The [.dockerignore](../.dockerignore) is a closed allowlist with later sensitive/cache exclusions. Unknown root files are excluded. Included source directories still require review: a filename denylist cannot detect arbitrary credentials embedded in allowed source. Synthetic context tests verify actual Docker ignore behavior, including hidden source skill directories, without reading personal credentials. The `context-audit` scratch stage is a test export target, never the runtime image. Package-data and MANIFEST include image resources so the installed wheel can pass kit validation.
+
+## Change impact and image refresh
+
+Assess image impact on every maintenance task, including changes outside Dockerfile. Canonical policy: [image freshness](../template/ai-kit/CONTAINERS.md#image-freshness).
+
+- Rebuild when CLI/scripts, installed templates/skills, ignore policies, integration resources, defaults or runtime dependencies change. Inspect Dockerfile COPY steps, `.dockerignore`, wheel package-data and MANIFEST: changing a source file is ineffective if packaging omits it. VERSION, build tools, base image, entrypoint and runtime-contract changes also require rebuilding and relevant checks.
+- Descriptive README/maintainer edits or publication receipts may retain the prepared image when runtime behavior and installed guidance stay unchanged; record that its bundled documentation is an earlier snapshot. Changes only in a mounted application or private dialogue workspace do not update the kit distribution and normally need no kit rebuild.
+- Build from final sources as `ai-kit:dev`, passing the current VERSION through AIKIT_VERSION. Keep the published `tigusigalpa/ai-kit:1.4.0` identity intact. Use normal cache invalidation; editing Dockerfile or disabling all cache is unnecessary for ordinary source changes.
+- Run kit validation, affected behavior tests and `python tests/docker_smoke.py ai-kit:dev --context .`; compare the changed packaged resources with source. Follow the verification procedure below for scope, preflight and cleanup. Keep artifact binaries and per-run identity/results outside the source checkout. Record a reason when no rebuild is needed; report runtime checks that could not run.
+- Local refresh does not refresh Docker Hub. Publish only under explicit authorization for the intended tag; an earlier one-time release push does not authorize future replacements. A requested release version must agree across VERSION, wheel and image label. Verify the remote digest/configuration after an authorized push.
+
+## Verification procedure
+
+1. Read the selected Docker context and both client/server versions; distinguish permissions from a stopped daemon. Build locally with the value from VERSION and record the tested architecture.
+2. Run `python scripts/check_kit.py` and `python -m unittest discover -s tests -v` after packaging/checker changes. Keep wheel output in an isolated source copy so tests cannot copy locked build artifacts.
+3. Build `docker build --build-arg AIKIT_VERSION=<value> --tag ai-kit:<value> .` and run `python tests/docker_smoke.py ai-kit:<value> --context .`. An optional `--builder NAME` scopes the synthetic context export to a dedicated builder.
+4. Check a missing/mismatched version build refuses. Inspect image user, labels, entrypoint and architecture; exercise the packaged wheel without host sources.
+5. Validate the [Job](../deploy/k8s/install-preview-job.yaml) against the target Kubernetes schema. Cluster dry-run and startup require a separately verified cluster context and existing PVC. No cluster deployment is part of image integration.
+6. Inspect the project test resource inventory after successful or failed runs. Measure owned volumes/cache without double-counting builder storage. Remove only eligible disposable resources when the canonical combined size is strictly above 10,000,000,000 bytes; a shared builder's records require ownership evidence. Never use unscoped system/volume/builder pruning.
+
+[docker_smoke.py](../tests/docker_smoke.py) checks non-root execution, matching version/label, no service/anonymous-volume contract, offline read-only help/route/check, a project path with spaces, read-only preview and refusal, installation of all four opt-in modules, preserved project/client documents, doctor, design context selection, stable rerun and SIGTERM in interactive preview. It removes only its own labeled temporary signal container; ordinary commands use `--rm`. It creates no Docker volumes. Linux callers forward a non-root host UID/GID for bind ownership; Windows uses the image default. Unit tests cover the version guard and safe command construction without requiring Docker.
+
+The new `Docker CLI` CI job builds and smoke-tests locally on Ubuntu. Existing validation/wheel check names are unchanged. Hosted execution and branch-protection changes need their own evidence/authorization.
+
+## Kubernetes contract
+
+The supplied batch/v1 Job is a read-only preview, not an apply operation: `install /workspace --agent codex`. `backoffLimit: 0` avoids retrying a one-shot operation automatically. It has a 300-second deadline, 30-second termination grace, non-root UID/GID, RuntimeDefault seccomp, dropped capabilities, no privilege escalation, no service-account token and read-only root. It reads an existing PVC and writes temporary files to a bounded emptyDir. It has no Service or artificial probe.
+
+`ai-kit:local`/Never requires that local image on the selected nodes. Use a reviewed registry digest/pull policy for other environments. Storage must be readable by UID 10001; no ownership mutation or fsGroup policy is assumed. CPU 100m/1 and memory 128Mi/512Mi are initial estimates, to be measured for the actual project. Add configuration, authentication or network controls only when the selected command needs them.
+
+## Verification results
+
+Current release labeling, tagged image and package checks: [v1.4.1](V1_4_1.md#verification). The initial integration results below retain their original date and version.
+
+Verified locally on 2026-10-14:
+
+- Docker Desktop 4.95.0 (242831), client/server 29.8.2, selected `desktop-linux` daemon, BuildKit v0.33.1. Built and smoke-tested `ai-kit:1.3.0` on linux/amd64. Runtime Python 3.13.16, Git 2.39.5 and AI-KIT 1.3.0 matched the declared image identity; default UID/GID was 10001:10001. Missing and mismatched version builds refused at the guard.
+- Actual container smoke passed with network disabled, read-only root, temporary storage and a Windows bind mount containing spaces: preview, read-only apply refusal, all four extras with Codex/Claude entries, preserved README/MCP bytes, doctor, design context and stable rerun. Docker's ignore engine included hidden source skills and excluded synthetic secret/private files. Interactive preview received SIGTERM and exited 143 without a forced kill. Alternate UID/GID 1002:1003 installed and checked a project on temporary storage with matching created-file ownership.
+- Full Windows/Python 3.12.14 discovery: 309 tests in 575.738 seconds, 307 passed and two skips (symlink privilege and unavailable POSIX sh). Both junction tests ran. Full packaged Linux/Python 3.13.16 discovery under a non-root, offline, read-only container: 309 tests in 29.096 seconds, 307 passed and two Windows-junction skips. These runs preceded the final result/ADR documentation; final packaging and kit/image checks follow that documentation update.
+- Windows wheel built in an isolated source copy without network dependency resolution; offline fresh-venv smoke passed, including all opt-in modules and packaged Docker resources. Added Python files parsed with Python 3.10 grammar. Kit validation and diff review were clean.
+- Job YAML passed strict field/type validation against the official [Kubernetes v1.35.0 OpenAPI schema](https://github.com/kubernetes/kubernetes/blob/v1.35.0/api/openapi-spec/swagger.json), with local preview/security assertions. Download SHA-256: `483500149ee52ce5753d75f5639101d985bb4f5e902cc05b1ba7627465d62446`. This is static schema coverage, not admission or storage/startup acceptance.
+- Test containers were removed; no test Docker volumes were created. The shared `desktop-linux` builder and existing volumes contain unrelated resources, so project cache bytes/ownership could not be isolated. No cache/volume prune was performed. The local CLI image is retained; per-run inventory is kept in the task report.
+
+Registry publication, hosted CI, macOS execution, other image architectures and Kubernetes server dry-run/deployment were not run. Native AI client activation, model calls, real benchmarks, framework/browser acceptance and security scans remain separate work.

aikit/docs/DOCKER_HUB_OVERVIEW.md

@@ -0,0 +1,311 @@
+# AI-KIT
+
+**Give your AI coding agents persistent project context, reusable skills and a consistent engineering workflow.**
+
+AI-KIT installs portable project instructions, stack profiles, client configuration and optional skills into your repository. It helps coding agents understand your project, preserve decisions, follow your conventions and verify their work.
+
+The Docker image packages the installer and CLI helpers with Python, Git, templates and integration resources. You can use AI-KIT without installing Python on your host.
+
+**Current image:** `tigusigalpa/ai-kit:1.4.1`
+
+**Published platform:** `linux/amd64`
+
+**Source:** [github.com/tigusigalpa/ai-kit](https://github.com/tigusigalpa/ai-kit)
+
+## What AI-KIT provides
+
+| Capability | Description |
+| --- | --- |
+| **Persistent project context** | Project facts, module maps, commands, decisions and continuity instructions that agents can reuse across chats. |
+| **Configuration for 11 AI clients** | Adapters for Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, Roo, Aider, Kimi and Manus. Discovery and activation depend on the selected client. |
+| **Stack-specific guidance** | Profiles for Go, PHP, Laravel, Filament, Moodle, Python, frontend, libraries, Rust, .NET, Java and Terraform/Helm. |
+| **Preview-first installation** | Review proposed changes before writing. Existing project documents and local modifications follow preservation and conflict rules. |
+| **Engineering workflows** | Plan, implement, test, review and document, supported by bootstrap, review and context synchronization skills. |
+| **Optional Web Design** | Reference analysis, project briefs, visual systems, stack-aware implementation guidance and UI acceptance criteria, including a Laravel Blade route. |
+| **Optional security workflows** | Pinned Cloudflare security-audit references and Strix workflow skills, installed explicitly and invoked on request. |
+| **Optional Context7 guidance** | Version-aware documentation lookup workflows, with client connection setup handled separately. |
+| **Shared dialogue context** | Local conversation imports, source references, contradiction review and exports for ChatGPT and OpenRouter. |
+| **Routing and evaluation helpers** | Model-routing recommendations, context selection, local metrics and benchmark scaffolding. Actual model execution requires a separately configured runtime. |
+| **Docker and Kubernetes guidance** | Container security, lifecycle, image freshness and deployment instructions, plus a Kubernetes installation-preview Job example. |
+
+AI-KIT installs instructions and supporting tools. Your coding client performs the development work.
+
+## What changed in v1.4.1
+
+### Docker image freshness
+
+Installed project instructions now ask agents to assess Docker impact whenever the project has images.
+
+When changes affect an image, the workflow calls for updating build inputs where needed, rebuilding the image and checking its actual behavior. This covers packaged code, instructions, templates, defaults and dependencies.
+
+These are maintenance instructions; rebuilding and publishing still happen through the project's tools and authorization rules.
+
+### Local maintainer files excluded
+
+The following root AI-KIT maintainer documents are excluded from the Docker build context and Python distributions:
+
+- `AGENTS.md`
+- `PROJECT_CONTEXT.md`
+- `WIKI.md`
+
+Their **application template counterparts remain included** and can still be installed into your projects.
+
+Public maintenance documentation now starts at `CONTRIBUTING.md`. Validation supports clean distributions without the optional local maintainer documents.
+
+### Packaging and upgrade verification
+
+The release includes regression coverage for package exclusions, template preservation and public links.
+
+Verification included:
+
+- 339 packaged Linux tests: **337 passed, two Windows-specific skips**.
+- Nine Windows CLI tests.
+- Actual Docker smoke tests, including offline execution, read-only behavior, installation, preservation, stable reruns and SIGTERM.
+- Offline wheel installation into a clean environment.
+- Upgrade fixtures from 1.4.0 in private and team modes.
+
+## Pull and check the image
+
+Docker must be running with Linux-container support.
+
+```sh
+docker pull tigusigalpa/ai-kit:1.4.1
+```
+
+Check the CLI help:
+
+```sh
+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
+```
+
+Arguments after the image name go directly to `aikit`. Running the image without arguments displays CLI help.
+
+The commands below disable runtime networking. Pulling the image still requires registry access.
+
+## Install into a project: Linux or Bash
+
+Choose an existing application directory. Run as an ordinary host user so the forwarded UID/GID is non-root.
+
+```bash
+app_path="$(cd /absolute/path/to/my-app && pwd)"
+image="tigusigalpa/ai-kit:1.4.1"
+
+runtime=(
+  --rm --init
+  --network none
+  --read-only
+  --cap-drop ALL
+  --security-opt no-new-privileges
+  --tmpfs /tmp:rw,nosuid,nodev,size=256m
+  --user "$(id -u):$(id -g)"
+)
+```
+
+Preview the installation with a read-only project mount:
+
+```bash
+docker run "${runtime[@]}" \
+  --mount "type=bind,source=$app_path,target=/workspace,readonly" \
+  "$image" install /workspace --agent codex
+```
+
+After reviewing the preview, apply using a writable project mount:
+
+```bash
+docker run "${runtime[@]}" \
+  --mount "type=bind,source=$app_path,target=/workspace" \
+  "$image" install /workspace --agent codex --apply --check
+```
+
+Check the installed project later:
+
+```bash
+docker run "${runtime[@]}" \
+  --mount "type=bind,source=$app_path,target=/workspace,readonly" \
+  "$image" doctor /workspace
+```
+
+Files written into `/workspace` persist in the mounted host directory after the container exits.
+
+## Install into a project: Windows PowerShell
+
+Use an existing application folder accessible to Docker Desktop.
+
+```powershell
+$appPath = (Resolve-Path -LiteralPath 'C:\Projects\my-app').Path
+$image = 'tigusigalpa/ai-kit:1.4.1'
+
+$runtime = @(
+    '--rm', '--init',
+    '--network', 'none',
+    '--read-only',
+    '--cap-drop', 'ALL',
+    '--security-opt', 'no-new-privileges',
+    '--tmpfs', '/tmp:rw,nosuid,nodev,size=256m'
+)
+```
+
+Preview:
+
+```powershell
+docker run @runtime `
+  --mount "type=bind,source=$appPath,target=/workspace,readonly" `
+  $image install /workspace --agent codex
+```
+
+Apply after reviewing the preview:
+
+```powershell
+docker run @runtime `
+  --mount "type=bind,source=$appPath,target=/workspace" `
+  $image install /workspace --agent codex --apply --check
+```
+
+Check the installed project:
+
+```powershell
+docker run @runtime `
+  --mount "type=bind,source=$appPath,target=/workspace,readonly" `
+  $image doctor /workspace
+```
+
+The image uses UID/GID `10001:10001` by default. Docker Desktop file sharing must permit access to the mounted folder.
+
+## Enable optional modules
+
+Optional modules are selected explicitly and remain independent of installation presets.
+
+| Installer option | Installs |
+| --- | --- |
+| `--with-web-design` | Design skills, conditional guides and project design documents. |
+| `--with-context7` | Context7 documentation lookup guidance and skill entry points. |
+| `--with-security-audit` | Pinned Cloudflare security-audit resources and an explicit entry point. |
+| `--with-strix` | Pinned Strix workflow references and an explicit entry point. |
+
+For example, in the Bash session above, preview a Codex and Claude Code installation with all four modules:
+
+```bash
+docker run "${runtime[@]}" \
+  --mount "type=bind,source=$app_path,target=/workspace,readonly" \
+  "$image" install /workspace \
+  --agent codex --agent claude \
+  --with-web-design \
+  --with-context7 \
+  --with-security-audit \
+  --with-strix
+```
+
+To apply that selection, use a writable project mount and append `--apply --check`, keeping the same agent and module options.
+
+Installing these modules does not start a security scan, connect an MCP server or invoke a model. External tools and client activation are configured separately.
+
+## Shared context from conversations
+
+AI-KIT can import two local dialogues and prepare a shared reference state.
+
+Supported inputs include:
+
+- ChatGPT-style conversation JSON with explicit conversation or branch selection when needed.
+- OpenRouter-style `messages` JSON.
+- UTF-8 text or Markdown transcripts from other clients.
+
+The workflow is:
+
+1. Import each conversation into a private workspace.
+2. Merge the imports and generate a review worksheet.
+3. Review claims and resolve explicit contradictions.
+4. Export ChatGPT Markdown and/or an OpenRouter JSON request fragment.
+
+Explore the commands without mounting any project:
+
+```bash
+docker run "${runtime[@]}" "$image" memory --help
+docker run "${runtime[@]}" "$image" memory import --help
+docker run "${runtime[@]}" "$image" memory merge --help
+docker run "${runtime[@]}" "$image" memory export --help
+```
+
+Imports, merges and exports preview by default; `--apply` writes local artifacts. Use a writable mount for the workspace and readable mounts for source transcripts.
+
+Normal exports require review. Explicit draft exports can retain pending claims and unresolved alternatives. Free-form semantic disagreements require human review.
+
+ChatGPT output is reference Markdown for manual use. OpenRouter output contains a reference message for your own client to include in a request. This workflow does not synchronize accounts, upload conversations or execute API calls.
+
+See the [shared dialogue context guide](https://github.com/tigusigalpa/ai-kit#shared-context-from-two-dialogues).
+
+## Other useful commands
+
+Using the Bash runtime options defined above:
+
+```bash
+# Show CLI help.
+docker run "${runtime[@]}" "$image" --help
+
+# Validate the bundled AI-KIT distribution.
+docker run "${runtime[@]}" "$image" check
+
+# Inspect a routing recommendation.
+docker run "${runtime[@]}" "$image" route "review an interface"
+
+# Show provider records.
+docker run "${runtime[@]}" "$image" providers
+```
+
+`check` validates the bundled distribution. `doctor /workspace` examines an installed application project.
+
+For a project with Web Design enabled:
+
+```bash
+docker run "${runtime[@]}" \
+  --mount "type=bind,source=$app_path,target=/workspace,readonly" \
+  "$image" context select /workspace --workflow web-design
+```
+
+Context selection reports the relevant files and their scope. It does not send them to a model.
+
+## Runtime contract
+
+| Setting | Value |
+| --- | --- |
+| Entrypoint | `aikit` |
+| Default command | `--help` |
+| Published platform | `linux/amd64` |
+| Default user | UID/GID `10001:10001` |
+| Working directory | `/workspace` |
+| Temporary writable storage | `/tmp`, supplied by the caller |
+| Exposed ports | None |
+| Shutdown signal | SIGTERM |
+
+The image is a CLI workload. Each invocation runs a command and exits.
+
+Python, Git and AI-KIT resources are bundled. Application toolchains, browsers, Node.js, Composer, model runtimes, MCP connections and the Strix executable are separate.
+
+The examples use a read-only container root and explicit project mounts. Preview commands can use read-only mounts; installation and other explicit writes require writable mounts.
+
+## Updates and reproducible references
+
+To update a project, pull the selected image version, preview installation against the same project folder and review any conflicts before applying.
+
+Existing project documents, settings, private dialogue memory and local edits retain the normal preservation rules.
+
+For an immutable reference to this published build:
+
+```sh
+docker pull tigusigalpa/ai-kit@sha256:d11fc24026f13ad90d3ef7a39a235fa40db29ff022999cff3585e7e707978370
+```
+
+Use the explicit version tag or digest. This release did not assign a `latest` tag.
+
+## Documentation and license
+
+- [Source repository and README](https://github.com/tigusigalpa/ai-kit)
+- [Docker usage](https://github.com/tigusigalpa/ai-kit#run-ai-kit-with-docker)
+- [Web Design](https://github.com/tigusigalpa/ai-kit#web-design)
+- [Shared dialogue context](https://github.com/tigusigalpa/ai-kit#shared-context-from-two-dialogues)
+- [OpenRouter guidance](https://github.com/tigusigalpa/ai-kit#working-with-openrouter)
+
+AI-KIT is licensed under MIT. Bundled Cloudflare references retain MIT licensing; bundled Strix references retain Apache-2.0 licensing.

aikit/docs/EVALUATION.md

@@ -0,0 +1,30 @@
+# Real-project evaluation protocol
+
+This protocol prepares application trials; it contains no measured application results. The owner chose to run the real-project trials separately. Synthetic routing and installer regressions validate implementation behavior, not productivity or savings.
+
+## First experiment: instructions with a fixed model
+
+1. Select a representative repository and record its starting revision, actual stack/versions, runnable checks, and allowed files. Use isolated disposable checkouts and a disposable database for each run; never reuse changes from the other arm.
+2. Define a small task set before running anything: mechanical edit, substantive feature, bug diagnosis, authorization/tenant boundary, and fresh-session continuation. Include Filament tasks only if the application actually uses Filament. For each task write an identical prompt, acceptance rubric, scope, required checks, and stopping rule. Include tasks where the kit may add overhead. Use `scripts/evaluate.py scaffold` to create an opaque private baseline/kit task-ID pack, not a prompt or evidence store.
+3. Arm A uses the project's existing instructions; arm B adds a reviewed AI-KIT installation. Preserve the same project facts, source starting state, tools, permissions, provider, actual model, effort, context/output limits, and runtime settings. Disable adaptive model changes in this experiment. Record the kit version and installation choices.
+4. Start a fresh session for every run. Balance/randomize A/B order, repeat task pairs, and record model/version and pricing dates when runs occur. Do not feed one arm's answer, patch, or corrections into the other. Account for bootstrap/context preparation time separately and for every retry/review/recovery call within the task.
+5. Apply the predeclared rubric and checks. Prefer a reviewer unaware of the arm, when available and authorized. Mark failures, unavailable checks, and incomplete work explicitly. Avoid treating compilation or tests alone as full semantic correctness. Record code scope violations or unintended edits in the private trial notes.
+6. Collect actual runtime telemetry; store one reviewed task record with all attempts through [metrics.py](../scripts/metrics.py) using the [measurement contract](../template/ai-kit/METRICS.md). A generated route/configuration is not telemetry. Use opaque matched task IDs and private notes. Baseline records may use `kit_version: "not-used"`.
+
+Run `scripts/evaluate.py coverage PROJECT --tasks PRIVATE_PACK` before comparing results. It reports missing baseline/kit pairs and unexpected journal records, but cannot assess semantic equivalence. Compare matched correctness and failure rate before cost/time. Report total cost per correct result, rework, recovery/escalations, duration coverage, input/output/reasoning/cache token coverage, and bootstrap overhead. Include failed tasks in spend. Separate billed/usage-derived costs from estimates, keep currencies separate, and report missing observations. Small samples support provisional conclusions; do not publish a savings percentage when arms or telemetry are not comparable.
+
+## Context and continuation checks
+
+For a mixed repository, pick one affected module. Observe which context/profile files are loaded: the active module's minimum needed rules and relevant shared boundaries should be selected from PROJECT_CONTEXT/WIKI. Unrelated stack/provider profiles should not be loaded by default. Record loaded bytes/tokens only when actually observable; do not substitute file size for token usage.
+
+For continuation, end a session after documenting verified facts, commands, decisions, and unresolved work. Start another session with the same repository state and task handoff but without the previous chat. Check whether the agent recovers module paths, commands, defaults, Git authorization limits, and remaining work correctly. Measure rereads/corrections and accidental unrelated edits. The existing context map and continuity skills guide this process; no automatic context engine is claimed.
+
+## Second experiment: routing
+
+Hold the adopted instruction setup fixed, then compare fixed-model execution with reviewed routing recommendations on matched tasks. Record the recommended level/model/effort separately from what the client actually executed. Manual risk/operation inputs must have the same evidence available across runs. Diagnose missing facts, ambiguous tasks, tool failures, and environment failures before model escalation; level 6 needs a documented capability reason.
+
+The offline helper does not switch live models, invoke delegates, or measure calls. Trials must verify client controls explicitly. Evaluate cost to a correct result including escalation and retained context, rather than initial-call price. Add orchestration only after a measured improvement justifies its operational complexity.
+
+## Trial notes template
+
+Keep this file in the project's ignored `ai-kit/.metrics/` directory. Record experiment ID, starting revisions, kit version/choices, task IDs, acceptance rubrics, run order, timestamps, actual model/settings, tools, check commands/results/skips, reviewer disposition, cost/pricing provenance, missing telemetry, and deviations. Store no secrets or production data. Summaries may be shared after reviewing their contents and receiving the owner's publication authorization.