@oscharko-dev/keiko 0.3.1 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (165) hide show
  1. package/README.md +59 -615
  2. package/dist/ui/csp-hashes.json +13 -13
  3. package/dist/ui/static/404.html +1 -1
  4. package/dist/ui/static/__next.__PAGE__.txt +1 -1
  5. package/dist/ui/static/__next._full.txt +1 -1
  6. package/dist/ui/static/__next._head.txt +1 -1
  7. package/dist/ui/static/__next._index.txt +1 -1
  8. package/dist/ui/static/__next._tree.txt +1 -1
  9. package/dist/ui/static/_not-found/__next._full.txt +1 -1
  10. package/dist/ui/static/_not-found/__next._head.txt +1 -1
  11. package/dist/ui/static/_not-found/__next._index.txt +1 -1
  12. package/dist/ui/static/_not-found/__next._not-found.__PAGE__.txt +1 -1
  13. package/dist/ui/static/_not-found/__next._not-found.txt +1 -1
  14. package/dist/ui/static/_not-found/__next._tree.txt +1 -1
  15. package/dist/ui/static/_not-found.html +1 -1
  16. package/dist/ui/static/_not-found.txt +1 -1
  17. package/dist/ui/static/atlassian-connectors/__next._full.txt +1 -1
  18. package/dist/ui/static/atlassian-connectors/__next._head.txt +1 -1
  19. package/dist/ui/static/atlassian-connectors/__next._index.txt +1 -1
  20. package/dist/ui/static/atlassian-connectors/__next._tree.txt +1 -1
  21. package/dist/ui/static/atlassian-connectors/__next.atlassian-connectors.__PAGE__.txt +1 -1
  22. package/dist/ui/static/atlassian-connectors/__next.atlassian-connectors.txt +1 -1
  23. package/dist/ui/static/atlassian-connectors.html +1 -1
  24. package/dist/ui/static/atlassian-connectors.txt +1 -1
  25. package/dist/ui/static/index.html +1 -1
  26. package/dist/ui/static/index.txt +1 -1
  27. package/dist/ui/static/launch/__next._full.txt +1 -1
  28. package/dist/ui/static/launch/__next._head.txt +1 -1
  29. package/dist/ui/static/launch/__next._index.txt +1 -1
  30. package/dist/ui/static/launch/__next._tree.txt +1 -1
  31. package/dist/ui/static/launch/__next.launch.__PAGE__.txt +1 -1
  32. package/dist/ui/static/launch/__next.launch.txt +1 -1
  33. package/dist/ui/static/launch.html +1 -1
  34. package/dist/ui/static/launch.txt +1 -1
  35. package/dist/ui/static/local-knowledge/__next._full.txt +1 -1
  36. package/dist/ui/static/local-knowledge/__next._head.txt +1 -1
  37. package/dist/ui/static/local-knowledge/__next._index.txt +1 -1
  38. package/dist/ui/static/local-knowledge/__next._tree.txt +1 -1
  39. package/dist/ui/static/local-knowledge/__next.local-knowledge.__PAGE__.txt +1 -1
  40. package/dist/ui/static/local-knowledge/__next.local-knowledge.txt +1 -1
  41. package/dist/ui/static/local-knowledge/capsule/__next._full.txt +1 -1
  42. package/dist/ui/static/local-knowledge/capsule/__next._head.txt +1 -1
  43. package/dist/ui/static/local-knowledge/capsule/__next._index.txt +1 -1
  44. package/dist/ui/static/local-knowledge/capsule/__next._tree.txt +1 -1
  45. package/dist/ui/static/local-knowledge/capsule/__next.local-knowledge.capsule.__PAGE__.txt +1 -1
  46. package/dist/ui/static/local-knowledge/capsule/__next.local-knowledge.capsule.txt +1 -1
  47. package/dist/ui/static/local-knowledge/capsule/__next.local-knowledge.txt +1 -1
  48. package/dist/ui/static/local-knowledge/capsule.html +1 -1
  49. package/dist/ui/static/local-knowledge/capsule.txt +1 -1
  50. package/dist/ui/static/local-knowledge.html +1 -1
  51. package/dist/ui/static/local-knowledge.txt +1 -1
  52. package/dist/ui/static/memoriaviva/__next._full.txt +1 -1
  53. package/dist/ui/static/memoriaviva/__next._head.txt +1 -1
  54. package/dist/ui/static/memoriaviva/__next._index.txt +1 -1
  55. package/dist/ui/static/memoriaviva/__next._tree.txt +1 -1
  56. package/dist/ui/static/memoriaviva/__next.memoriaviva.__PAGE__.txt +1 -1
  57. package/dist/ui/static/memoriaviva/__next.memoriaviva.txt +1 -1
  58. package/dist/ui/static/memoriaviva/consolidation/__next._full.txt +1 -1
  59. package/dist/ui/static/memoriaviva/consolidation/__next._head.txt +1 -1
  60. package/dist/ui/static/memoriaviva/consolidation/__next._index.txt +1 -1
  61. package/dist/ui/static/memoriaviva/consolidation/__next._tree.txt +1 -1
  62. package/dist/ui/static/memoriaviva/consolidation/__next.memoriaviva.consolidation.__PAGE__.txt +1 -1
  63. package/dist/ui/static/memoriaviva/consolidation/__next.memoriaviva.consolidation.txt +1 -1
  64. package/dist/ui/static/memoriaviva/consolidation/__next.memoriaviva.txt +1 -1
  65. package/dist/ui/static/memoriaviva/consolidation.html +1 -1
  66. package/dist/ui/static/memoriaviva/consolidation.txt +1 -1
  67. package/dist/ui/static/memoriaviva/detail/__next._full.txt +1 -1
  68. package/dist/ui/static/memoriaviva/detail/__next._head.txt +1 -1
  69. package/dist/ui/static/memoriaviva/detail/__next._index.txt +1 -1
  70. package/dist/ui/static/memoriaviva/detail/__next._tree.txt +1 -1
  71. package/dist/ui/static/memoriaviva/detail/__next.memoriaviva.detail.__PAGE__.txt +1 -1
  72. package/dist/ui/static/memoriaviva/detail/__next.memoriaviva.detail.txt +1 -1
  73. package/dist/ui/static/memoriaviva/detail/__next.memoriaviva.txt +1 -1
  74. package/dist/ui/static/memoriaviva/detail.html +1 -1
  75. package/dist/ui/static/memoriaviva/detail.txt +1 -1
  76. package/dist/ui/static/memoriaviva/health-scan/__next._full.txt +1 -1
  77. package/dist/ui/static/memoriaviva/health-scan/__next._head.txt +1 -1
  78. package/dist/ui/static/memoriaviva/health-scan/__next._index.txt +1 -1
  79. package/dist/ui/static/memoriaviva/health-scan/__next._tree.txt +1 -1
  80. package/dist/ui/static/memoriaviva/health-scan/__next.memoriaviva.health-scan.__PAGE__.txt +1 -1
  81. package/dist/ui/static/memoriaviva/health-scan/__next.memoriaviva.health-scan.txt +1 -1
  82. package/dist/ui/static/memoriaviva/health-scan/__next.memoriaviva.txt +1 -1
  83. package/dist/ui/static/memoriaviva/health-scan.html +1 -1
  84. package/dist/ui/static/memoriaviva/health-scan.txt +1 -1
  85. package/dist/ui/static/memoriaviva/journal/__next._full.txt +1 -1
  86. package/dist/ui/static/memoriaviva/journal/__next._head.txt +1 -1
  87. package/dist/ui/static/memoriaviva/journal/__next._index.txt +1 -1
  88. package/dist/ui/static/memoriaviva/journal/__next._tree.txt +1 -1
  89. package/dist/ui/static/memoriaviva/journal/__next.memoriaviva.journal.__PAGE__.txt +1 -1
  90. package/dist/ui/static/memoriaviva/journal/__next.memoriaviva.journal.txt +1 -1
  91. package/dist/ui/static/memoriaviva/journal/__next.memoriaviva.txt +1 -1
  92. package/dist/ui/static/memoriaviva/journal.html +1 -1
  93. package/dist/ui/static/memoriaviva/journal.txt +1 -1
  94. package/dist/ui/static/memoriaviva/review-queue/__next._full.txt +1 -1
  95. package/dist/ui/static/memoriaviva/review-queue/__next._head.txt +1 -1
  96. package/dist/ui/static/memoriaviva/review-queue/__next._index.txt +1 -1
  97. package/dist/ui/static/memoriaviva/review-queue/__next._tree.txt +1 -1
  98. package/dist/ui/static/memoriaviva/review-queue/__next.memoriaviva.review-queue.__PAGE__.txt +1 -1
  99. package/dist/ui/static/memoriaviva/review-queue/__next.memoriaviva.review-queue.txt +1 -1
  100. package/dist/ui/static/memoriaviva/review-queue/__next.memoriaviva.txt +1 -1
  101. package/dist/ui/static/memoriaviva/review-queue.html +1 -1
  102. package/dist/ui/static/memoriaviva/review-queue.txt +1 -1
  103. package/dist/ui/static/memoriaviva.html +1 -1
  104. package/dist/ui/static/memoriaviva.txt +1 -1
  105. package/node_modules/@oscharko-dev/keiko-cli/package.json +13 -13
  106. package/node_modules/@oscharko-dev/keiko-connectors/package.json +3 -3
  107. package/node_modules/@oscharko-dev/keiko-contracts/dist/index.d.ts +2 -2
  108. package/node_modules/@oscharko-dev/keiko-contracts/dist/index.js +2 -2
  109. package/node_modules/@oscharko-dev/keiko-contracts/package.json +1 -1
  110. package/node_modules/@oscharko-dev/keiko-evaluations/package.json +9 -9
  111. package/node_modules/@oscharko-dev/keiko-evidence/dist/version.d.ts +1 -1
  112. package/node_modules/@oscharko-dev/keiko-evidence/dist/version.js +1 -1
  113. package/node_modules/@oscharko-dev/keiko-evidence/package.json +4 -4
  114. package/node_modules/@oscharko-dev/keiko-git/package.json +1 -1
  115. package/node_modules/@oscharko-dev/keiko-harness/dist/version.d.ts +1 -1
  116. package/node_modules/@oscharko-dev/keiko-harness/dist/version.js +1 -1
  117. package/node_modules/@oscharko-dev/keiko-harness/package.json +6 -6
  118. package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/version.d.ts +1 -1
  119. package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/version.js +1 -1
  120. package/node_modules/@oscharko-dev/keiko-local-knowledge/package.json +5 -5
  121. package/node_modules/@oscharko-dev/keiko-memory-capture/dist/version.d.ts +1 -1
  122. package/node_modules/@oscharko-dev/keiko-memory-capture/dist/version.js +1 -1
  123. package/node_modules/@oscharko-dev/keiko-memory-capture/package.json +3 -3
  124. package/node_modules/@oscharko-dev/keiko-memory-consolidation/dist/version.d.ts +1 -1
  125. package/node_modules/@oscharko-dev/keiko-memory-consolidation/dist/version.js +1 -1
  126. package/node_modules/@oscharko-dev/keiko-memory-consolidation/package.json +3 -3
  127. package/node_modules/@oscharko-dev/keiko-memory-governance/dist/version.d.ts +1 -1
  128. package/node_modules/@oscharko-dev/keiko-memory-governance/dist/version.js +1 -1
  129. package/node_modules/@oscharko-dev/keiko-memory-governance/package.json +3 -3
  130. package/node_modules/@oscharko-dev/keiko-memory-retrieval/dist/version.d.ts +1 -1
  131. package/node_modules/@oscharko-dev/keiko-memory-retrieval/dist/version.js +1 -1
  132. package/node_modules/@oscharko-dev/keiko-memory-retrieval/package.json +3 -3
  133. package/node_modules/@oscharko-dev/keiko-memory-vault/dist/version.d.ts +1 -1
  134. package/node_modules/@oscharko-dev/keiko-memory-vault/dist/version.js +1 -1
  135. package/node_modules/@oscharko-dev/keiko-memory-vault/package.json +3 -3
  136. package/node_modules/@oscharko-dev/keiko-model-gateway/dist/version.d.ts +1 -1
  137. package/node_modules/@oscharko-dev/keiko-model-gateway/dist/version.js +1 -1
  138. package/node_modules/@oscharko-dev/keiko-model-gateway/package.json +3 -3
  139. package/node_modules/@oscharko-dev/keiko-quality-intelligence/package.json +3 -3
  140. package/node_modules/@oscharko-dev/keiko-sandbox/package.json +2 -2
  141. package/node_modules/@oscharko-dev/keiko-sdk/package.json +9 -9
  142. package/node_modules/@oscharko-dev/keiko-security/dist/version.d.ts +1 -1
  143. package/node_modules/@oscharko-dev/keiko-security/dist/version.js +1 -1
  144. package/node_modules/@oscharko-dev/keiko-security/package.json +2 -2
  145. package/node_modules/@oscharko-dev/keiko-server/dist/coding-runtime/productionCodingRuntimeResolver.js +4 -1
  146. package/node_modules/@oscharko-dev/keiko-server/dist/coding-runtime/runtimeAuthorityService.d.ts +9 -0
  147. package/node_modules/@oscharko-dev/keiko-server/dist/coding-runtime/runtimeAuthorityService.d.ts.map +1 -1
  148. package/node_modules/@oscharko-dev/keiko-server/dist/coding-runtime/runtimeAuthorityService.js +24 -1
  149. package/node_modules/@oscharko-dev/keiko-server/dist/deps.d.ts +1 -0
  150. package/node_modules/@oscharko-dev/keiko-server/dist/deps.d.ts.map +1 -1
  151. package/node_modules/@oscharko-dev/keiko-server/dist/deps.js +3 -3
  152. package/node_modules/@oscharko-dev/keiko-server/package.json +21 -21
  153. package/node_modules/@oscharko-dev/keiko-tools/dist/version.d.ts +1 -1
  154. package/node_modules/@oscharko-dev/keiko-tools/dist/version.js +1 -1
  155. package/node_modules/@oscharko-dev/keiko-tools/package.json +5 -5
  156. package/node_modules/@oscharko-dev/keiko-verification/package.json +5 -5
  157. package/node_modules/@oscharko-dev/keiko-workflows/package.json +10 -10
  158. package/node_modules/@oscharko-dev/keiko-workspace/dist/version.d.ts +1 -1
  159. package/node_modules/@oscharko-dev/keiko-workspace/dist/version.js +1 -1
  160. package/node_modules/@oscharko-dev/keiko-workspace/package.json +3 -3
  161. package/package.json +25 -25
  162. package/release-impact.catalog.json +116 -1
  163. /package/dist/ui/static/_next/static/{MCItfG-Jx7r8l8N0jlybM → OLvh_PREYwGT5IVJISFs9}/_buildManifest.js +0 -0
  164. /package/dist/ui/static/_next/static/{MCItfG-Jx7r8l8N0jlybM → OLvh_PREYwGT5IVJISFs9}/_clientMiddlewareManifest.js +0 -0
  165. /package/dist/ui/static/_next/static/{MCItfG-Jx7r8l8N0jlybM → OLvh_PREYwGT5IVJISFs9}/_ssgManifest.js +0 -0
package/README.md CHANGED
@@ -1,5 +1,5 @@
1
1
  <p align="center">
2
- <img src="https://raw.githubusercontent.com/oscharko-dev/Keiko/release/0.2.0/packages/keiko-ui/public/keiko-logo.svg" alt="Keiko logo" width="144" />
2
+ <img src="https://raw.githubusercontent.com/oscharko-dev/Keiko/dev/packages/keiko-ui/public/keiko-logo.svg" alt="Keiko logo" width="144" />
3
3
  </p>
4
4
 
5
5
  <h1 align="center">Keiko</h1>
@@ -7,670 +7,114 @@
7
7
  <p align="center"><strong>Ex experientia disco</strong></p>
8
8
 
9
9
  <p align="center">
10
- Keiko is a governed agentic workspace for knowledge work that learns from experience.
10
+ The governed agentic workspace for professional knowledge work.<br />
11
+ Local-first. Human-controlled. It learns from experience.<br />
12
+ Manifest-producing surfaces emit redacted evidence for audit.
11
13
  </p>
12
14
 
13
15
  <p align="center">
14
- <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache%202.0-4EBA87.svg"></a>
15
- <a href="package.json"><img alt="Node.js" src="https://img.shields.io/badge/node-24.18_LTS-4EBA87.svg?logo=node.js&logoColor=white"></a>
16
- <a href="package.json"><img alt="npm" src="https://img.shields.io/badge/npm-11.16.0-4EBA87.svg?logo=npm&logoColor=white"></a>
16
+ <a href="https://github.com/oscharko-dev/Keiko/blob/dev/LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache%202.0-4EBA87.svg"></a>
17
17
  <a href="https://github.com/oscharko-dev/Keiko/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/oscharko-dev/Keiko/actions/workflows/ci.yml/badge.svg?branch=dev"></a>
18
18
  <a href="https://github.com/oscharko-dev/Keiko/actions/workflows/codeql.yml"><img alt="CodeQL" src="https://github.com/oscharko-dev/Keiko/actions/workflows/codeql.yml/badge.svg?branch=dev"></a>
19
- <img alt="TypeScript" src="https://img.shields.io/badge/language-TypeScript-3178C6.svg?logo=typescript&logoColor=white">
19
+ <a href="https://sonarcloud.io/summary/new_code?id=oscharko-dev_Keiko"><img alt="Quality gate" src="https://sonarcloud.io/api/project_badges/measure?project=oscharko-dev_Keiko&metric=alert_status"></a>
20
20
  <img alt="Local first" src="https://img.shields.io/badge/runtime-local--first-1F2937.svg">
21
- <a href="https://sonarcloud.io/summary/new_code?id=oscharko-dev_Keiko"><img alt="SonarCloud Quality Gate" src="https://sonarcloud.io/api/project_badges/measure?project=oscharko-dev_Keiko&metric=alert_status"></a>
22
- <a href="https://sonarcloud.io/summary/new_code?id=oscharko-dev_Keiko"><img alt="SonarCloud Quality Gate" src="https://sonarcloud.io/api/project_badges/measure?project=oscharko-dev_Keiko&metric=ncloc"></a>
23
- <a href="https://sonarcloud.io/summary/new_code?id=oscharko-dev_Keiko"><img alt="SonarCloud Quality Gate" src="https://sonarcloud.io/api/project_badges/measure?project=oscharko-dev_Keiko&metric=coverage"></a>
24
- <a href="https://sonarcloud.io/summary/new_code?id=oscharko-dev_Keiko"><img alt="SonarCloud Quality Gate" src="https://sonarcloud.io/api/project_badges/measure?project=oscharko-dev_Keiko&metric=duplicated_lines_density"></a>
25
- <a href="https://sonarcloud.io/summary/new_code?id=oscharko-dev_Keiko"><img alt="SonarCloud Quality Gate" src="https://sonarcloud.io/api/project_badges/measure?project=oscharko-dev_Keiko&metric=reliability_rating"></a>
26
- <a href="https://sonarcloud.io/summary/new_code?id=oscharko-dev_Keiko"><img alt="SonarCloud Quality Gate" src="https://sonarcloud.io/api/project_badges/measure?project=oscharko-dev_Keiko&metric=security_rating"></a>
27
- <a href="https://sonarcloud.io/summary/new_code?id=oscharko-dev_Keiko"><img alt="SonarCloud Quality Gate" src="https://sonarcloud.io/api/project_badges/measure?project=oscharko-dev_Keiko&metric=sqale_rating"></a>
28
- <a href="https://sonarcloud.io/summary/new_code?id=oscharko-dev_Keiko"><img alt="SonarCloud Quality Gate" src="https://sonarcloud.io/api/project_badges/measure?project=oscharko-dev_Keiko&metric=sqale_index"></a>
29
- <a href="https://sonarcloud.io/summary/new_code?id=oscharko-dev_Keiko"><img alt="SonarCloud Quality Gate" src="https://sonarcloud.io/api/project_badges/measure?project=oscharko-dev_Keiko&metric=vulnerabilities"></a>
30
21
  </p>
31
22
 
32
- <p align="center">
33
- <a href="https://sonarcloud.io/project/overview?id=oscharko-dev_Keiko"><picture>
34
- <img src="https://sonarcloud.io/images/project_badges/sonarcloud-highlight.svg" width="340" alt="Scanned on SonarQube Cloud badge">
35
- </picture></a>
36
- </p>
37
-
38
- <!-- Review-record card, rendered on a schedule by Keiko-for-Quality's quality-cards workflow
39
- from GitHub API data. When quality.keiko.dev is deployed, only the URLs below change to
40
- https://quality.keiko.dev/widget/oscharko-dev/Keiko.svg . -->
41
23
  <p align="center">
42
24
  <a href="https://github.com/oscharko-dev/Keiko-for-Quality"><picture>
43
25
  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/oscharko-dev/Keiko-for-Quality/quality-cards/cards/oscharko-dev/Keiko-light.svg">
44
- <img src="https://raw.githubusercontent.com/oscharko-dev/Keiko-for-Quality/quality-cards/cards/oscharko-dev/Keiko.svg" width="340" alt="Reviewed by Keiko for Quality — run, finding and acted-on numbers for this repository">
26
+ <img src="https://raw.githubusercontent.com/oscharko-dev/Keiko-for-Quality/quality-cards/cards/oscharko-dev/Keiko.svg" width="340" alt="Reviewed by Keiko for Quality">
45
27
  </picture></a>
46
28
  </p>
47
29
 
48
30
  <p align="center">
49
- <a href="#quickstart">Quickstart</a>
31
+ <a href="#download">Download</a>
50
32
  ·
51
- <a href="#core-workflows">Workflows</a>
33
+ <a href="#quickstart-with-npm">npm</a>
52
34
  ·
53
- <a href="#security-boundaries">Security</a>
35
+ <a href="#whats-in-03">What's in 0.3</a>
54
36
  ·
55
- <a href="CONTRIBUTING.md">Contributing</a>
37
+ <a href="https://github.com/oscharko-dev/Keiko/blob/dev/CONTRIBUTING.md">Contributing</a>
56
38
  ·
57
- <a href="SECURITY.md">Security policy</a>
39
+ <a href="https://github.com/oscharko-dev/Keiko/blob/dev/SECURITY.md">Security policy</a>
58
40
  </p>
59
41
 
60
- ## Overview
61
-
62
- Keiko starts with local developer-assist workflows for regulated engineering teams. It helps inspect a repository, chat with configured language models, generate reviewable unit tests, investigate bugs, run verification, and keep redacted evidence for human review.
63
-
64
- Keiko is human-controlled by design: a local human selects or accepts the task, autonomy mode, and
65
- authority envelope. Inside that accepted authority, delivery is autonomous — agents commit, push
66
- their feature branch, and maintain the pull request, and GitHub native auto-merge integrates into
67
- `dev` automatically once the required quality gates are green on the exact current head and every
68
- review conversation is resolved. No human review or manual merge action is part of the loop; the
69
- gates are the control (ADR-0135). Direct pushes to
70
- `dev`, force pushes, and gate bypasses stay denied, and the manifest-producing surfaces emit
71
- redacted evidence for audit.
42
+ ---
72
43
 
73
- ## Vision
44
+ Keiko turns a repository, your documents and your models into one calm place to work: chat with the models you configure, understand a codebase, generate reviewable tests, investigate bugs, run verification — and keep a memory of what was learned along the way. Everything runs on your machine, every action stays within the authority you grant, and manifest-producing surfaces emit redacted evidence for audit.
74
45
 
75
- Keiko's long-term direction is a governed workspace where people can delegate knowledge work to learning agents without giving up control, oversight, or accountability.
46
+ ## What you get
76
47
 
77
- - **Governed delegation:** agents start with a task, not standing rights.
78
- - **Harness-first control:** agent actions, tool calls, connector access, approvals, failures, and outcomes flow through one observable control layer.
79
- - **Keiko Twin:** a governed work representative that can build controlled memory about user preferences, project routines, accepted outcomes, and recurring corrections.
80
- - **Learning from experience:** Keiko should improve future tool selection, escalation, policy suggestions, and workflow quality from structured evidence and feedback.
81
- - **Enterprise boundaries:** learning can improve suggestions and routines, but it must never grant itself authority or bypass human and organizational policy.
48
+ - **A workspace that understands your repository** — inspect, search and reason over real code, not snippets.
49
+ - **Chat with your own models** — bring the endpoints you already trust; Keiko never ships or hides credentials.
50
+ - **A coding workbench with a managed agent runtime** — the bundled OpenCode sidecar plans and edits inside a verified sandbox, under autonomy modes you choose.
51
+ - **Test generation, bug investigation, verification** — reviewable outcomes with honest state: no green over a broken gateway, every refusal names its reason.
52
+ - **Memory that learns from experience** — decisions and findings persist locally and sharpen future answers; local knowledge retrieval runs on a fast approximate-nearest-neighbour index.
53
+ - **Governance you can show an auditor** — human-controlled autonomy, fail-closed trust boundaries, and body-free evidence: counts, hashes and statuses, never your content.
82
54
 
83
- Software engineering is the first use case because repositories, tests, reviews, and tool calls create hard evidence. The product direction is broader: a controlled agentic workspace for enterprise knowledge work.
55
+ ## Download
84
56
 
85
- ## Report bugs and findings
57
+ The desktop packages install in one step and include everything — Node.js runtime and the OpenCode coding sidecar bundled, nothing else to install.
86
58
 
87
- If you find a defect while using Keiko, use the structured [User-Finding report form](https://github.com/oscharko-dev/Keiko/blob/dev/docs/user-finding-report.md). It is a public, account-free intake template that can be filled without signing in to GitHub.
59
+ **[Download the latest release →](https://github.com/oscharko-dev/Keiko/releases/latest)**
88
60
 
89
- Maintainers who are signed in to GitHub can transfer the same information into the tracked [GitHub User-Finding issue form](https://github.com/oscharko-dev/Keiko/issues/new?template=user_finding.yml). Do not open a blank issue for reproducible bug intake.
61
+ | Platform | Package |
62
+ | --------------------- | -------------------------------------------------------- |
63
+ | macOS (Apple Silicon) | `keiko-macos-arm64.zip` |
64
+ | macOS (Intel) | `keiko-macos-x64.zip` |
65
+ | Windows x64 | `keiko-windows-x64-setup.exe` or `keiko-windows-x64.zip` |
90
66
 
91
- The form captures version, platform, reproduction steps, expected behavior, actual behavior, impact, environment, and redacted evidence. Do not include API keys, customer data, private screenshots, internal model endpoints, private logs, or other secrets.
67
+ First launch: macOS asks once for **System Settings → Privacy & Security → Open Anyway** (the 0.3 line ships as an evaluation build without an Apple developer signature — stated plainly in every release). Windows shows the SmartScreen notice once — **More info → Run anyway**. Keiko then opens at `http://127.0.0.1:1983`.
92
68
 
93
- ## Quickstart
69
+ ## Quickstart with npm
94
70
 
95
- Install Keiko globally or use it directly in your project:
71
+ For developers who prefer the package manager path:
96
72
 
97
73
  ```bash
98
74
  npm install -g @oscharko-dev/keiko
99
- keiko init && keiko start
100
- ```
101
-
102
- The UI opens at `http://127.0.0.1:1983`. Configure a chat model in Settings, add a local project path, and start working with chat, test generation, bug investigation, or verification workflows.
103
-
104
- To stop Keiko: `keiko stop`.
105
-
106
- See [Install and start](#install-and-start) below for package-manager variations and the [Troubleshooting](#troubleshooting) section for setup issues.
107
-
108
- ## Developer quickstart
109
-
110
- Use this path when you want to work on Keiko itself rather than install it into another project.
111
-
112
- ### Prerequisites
113
-
114
- - Node.js 24.18.x LTS
115
- - npm 11.16.0 (bundled with the governed Node.js runtime)
116
- - A local clone of this repository
117
-
118
- ### Install dependencies
119
-
120
- ```bash
121
- npm install
122
75
  ```
123
76
 
124
- ### Run the repository checks
125
-
126
- There is deliberately no aggregate pre-PR wrapper (ADR-0145 retired it): run the minimum-loop
127
- commands scoped to what your change touches, plus the touched-area gates from `AGENTS.md`
128
- section 3; the required CI run on the pull request is the complete arbiter:
129
-
130
- ```bash
131
- npm run typecheck && npm run lint && npm run format:check && npm test && npm run arch:check && npm run arch:check:negative
132
- ```
133
-
134
- ### Start the repository in development mode
135
-
136
- ```bash
137
- npm run dev:start
138
- ```
139
-
140
- The development server starts the Node BFF, launches the Next.js UI, and binds to one loopback URL. Stop it with:
141
-
142
- ```bash
143
- npm run dev:stop
144
- ```
145
-
146
- ### Repository map
147
-
148
- | Path | Purpose |
149
- | ----------- | ------------------------------------------------------------------------------------------------------ |
150
- | `src/` | Root TypeScript entrypoints and shared runtime wiring. |
151
- | `packages/` | Workspace packages for the CLI, UI, contracts, workflows, security, memory, and supporting subsystems. |
152
- | `tests/` | Unit, integration, fixture, and Playwright end-to-end coverage. |
153
- | `docs/` | ADRs, operator runbooks, verification notes, and architecture documentation. |
154
- | `scripts/` | Build, validation, release, and repository maintenance scripts. |
155
- | `sandbox/` | Versioned install sandbox for packaged-application verification. |
156
-
157
- ### How to orient in the codebase
158
-
159
- Start with these files when you are new to the repository:
160
-
161
- - `CONTRIBUTING.md` for the required quality bar and CI expectations
162
- - `docs/adr/README.md` for the current architectural decisions
163
- - `package.json` for the supported scripts and release gates
164
- - `docs/troubleshooting/README.md` for operator-facing failure modes
165
-
166
- ## Repository development
167
-
168
- From the repository root, start the development UI:
169
-
170
- ```bash
171
- npm run dev:start
172
- ```
173
-
174
- This checks whether dependencies are installed, runs the root build needed by the Node BFF, starts
175
- the UI through `next dev`, and exposes the app through one loopback URL. If the default port
176
- `1983` is already in use and no port was explicitly configured, the script chooses the next free
177
- loopback port. On supported macOS checkouts it also verifies or prepares the approved coding
178
- runtime and does not report a successful start until runtime readiness is available. The dev
179
- server binds the loopback interface and prints a `localhost` browser URL.
180
-
181
- Stop the development UI:
182
-
183
77
  ```bash
184
- npm run dev:stop
78
+ keiko init && keiko start
185
79
  ```
186
80
 
187
- The stop command waits for the BFF to dispose the coding runtime and for every tracked development
188
- process to exit. Use `npm run dev:stop -- --force` only when bounded graceful shutdown fails.
189
-
190
- For a versioned sandbox that installs the current root package through `file:..`, rebuilds the
191
- packaged UI on every start, and then runs the built artifact, use [`sandbox/`](sandbox/).
192
-
193
- ## What's New in 0.2.0
194
-
195
- ### Quality Intelligence
196
-
197
- A native Workspace window that turns connected requirement sources into reviewable, evidence-backed test-case candidates. Open **Quality Intelligence** from the left rail, connect sources the same way Chat does — a single Fachkonzept file, folders, Knowledge Capsules, or a Figma snapshot, up to 16 at once — and press **Generate**. Quality Intelligence persists a redacted, integrity-hashed evidence manifest for each run. You get a coverage Gap Radar with per-requirement excerpts, a bidirectional requirement↔test traceability matrix (CSV/Markdown), drift detection with targeted regeneration ("Living Tests"), an optional adversarial test-quality judge, inline candidate editing, and export to PDF, Markdown, plain text, or a ZIP bundle. Quality Center export is a dry-run preview by design; live writes are rejected.
198
-
199
- Model use is capability-routed and optional: with no model configured, the structural stages still produce a deterministic baseline run.
81
+ Run it inside a project with a `package.json`; the UI opens at `http://127.0.0.1:1983` (`keiko stop` shuts it down, `keiko start --port <n>` picks another port). Configure a chat model in Settings, add a project path, and start working. The coding sidecar ships with the desktop packages above and with repository checkouts — the npm install reports it honestly as unavailable rather than pretending.
200
82
 
201
- ### Figma design connector
83
+ ## What's in 0.3
202
84
 
203
- Connect a Figma board read-only with a personal access token. The token is encrypted at rest with the same AES-256-GCM vault primitive as memory — the vault key comes from the macOS keychain, an environment variable, or a `0600` keyfile — and is never written to config files or logs. Keiko builds a deterministic clean Snapshot — screens, text, design tokens, navigation links — that can feed Quality Intelligence for design-to-tests, an accessibility baseline, and a first design-to-code slice. The connector is PAT-only, audited, consent-gated, and validates the exact `figma.com` host before any request.
85
+ - Multi-root editor workspaces with an explicit **Workspace Trust** gate — a new workspace stays restricted until you grant trust.
86
+ - Editor profiles, portable profile import/export, and per-file local history with a keyboard-operable timeline.
87
+ - Faster local knowledge: retrieval now runs on an approximate-nearest-neighbour index, built on demand from vectors you already have.
88
+ - Honest readiness everywhere — Coding Workbench, Chat, Git, Prompt Enhancer, MemoriaViva and Quality Intelligence report real state, and every refused action carries a copyable support id.
89
+ - Voice turns carry their attachments and document context; interrupting an answer cancels only that answer.
90
+ - Governed Git delivery authenticates on every network path and tells offline apart from authentication failure.
91
+ - First public download release: evaluation desktop packages for macOS and Windows with the OpenCode sidecar included.
204
92
 
205
- ### MemoriaViva governed memory
93
+ ## Good to know
206
94
 
207
- Keiko's memory is now encrypted at rest (AES-256-GCM vault, ADR-0035) — no plaintext memory content touches disk. Memories are captured from natural conversation when salient, decay and can be forgotten under governance rules (`keiko memory maintain`), and are recalled semantically via embeddings. The memory window is available from the left rail as **MemoriaViva**.
95
+ - The CLI, the UI and the SDK share one product. Surface coverage is intentionally not identical. `keiko gen-tests` and `keiko investigate` print a reviewable report but do not persist an evidence manifest.
96
+ - The UI can create a local runtime config during first-run setup. To list models, Keiko calls the gateway model list endpoint you configured — credentials stay in your local config.
97
+ - Keiko serves loopback only: `keiko start` and the UI validate a loopback host value, and the server always binds `127.0.0.1`. `keiko start --port <n>` sets the Port to bind (default: 1983).
98
+ - The full operator reference lives in the [UI runbook](https://github.com/oscharko-dev/Keiko/blob/dev/docs/ui-runbook.md).
208
99
 
209
- MemoriaViva is local machine state, not cloud telemetry or shared team memory. Memories are scoped
210
- to user, workspace, project, workflow, or global coordinates, and retrieval uses those scopes before
211
- adding any memory context to a model prompt. When memory is enabled for a conversation or workflow,
212
- Keiko may add a bounded, redacted memory context block to the model call; disabling memory or using
213
- memory-off mode omits that block. Forget/delete actions tombstone the selected memory for audit, and
214
- maintenance can archive, decay, forget stale records, or purge expired tombstones under
215
- deterministic retention rules. Diagnostics and audit exports are body-free: they report counts,
216
- status, scope summaries, and redacted audit events rather than raw memory bodies or structured
217
- payloads. Use `keiko memory diagnostics` for the local support snapshot; the Digital Twin panel
218
- does not maintain a separate browser-local memory store. See
219
- [Conversation Center privacy and retention](https://github.com/oscharko-dev/Keiko/blob/dev/docs/conversation-center-privacy.md)
220
- for the public memory privacy contract.
100
+ ## Principles
221
101
 
222
- ### Conversation Center and grounding
223
-
224
- Chat now streams tokens over SSE (first token in well under a second on TLS-intercepted enterprise networks). Grounded answers can draw on any local folder plus Local Knowledge connectors simultaneously; reciprocal-rank fusion keeps one source from starving the others, and grounding budgets are operator-configurable.
102
+ - **Human-controlled by design.** You select the task, the autonomy mode and the authority envelope; hard limits fail closed.
103
+ - **Local-first.** Your repositories, memory and evidence live on your machine.
104
+ - **Evidence over trust.** Manifests and audit exports carry counts, scopes and hashes — never raw content.
105
+ - **Honest state.** No silent failure, no green over broken.
225
106
 
226
107
  ## Requirements
227
108
 
228
- ### Requirements
229
-
230
- - Node.js 24.18.x LTS
231
- - npm 11.16.0
232
- - An OpenAI-compatible chat-completions gateway and an API token for model-backed work
233
-
234
- ### Install and start
235
-
236
- Install Keiko in the project where you want to use it, then run the local `keiko` binary:
237
-
238
- ```bash
239
- # npm
240
- npm install -D @oscharko-dev/keiko
241
- npx keiko init
242
- npm run keiko:start
243
-
244
- # yarn
245
- yarn add -D @oscharko-dev/keiko
246
- yarn keiko init
247
- yarn keiko:start
248
-
249
- # pnpm
250
- pnpm add -D @oscharko-dev/keiko
251
- pnpm exec keiko init
252
- pnpm keiko:start
253
- ```
254
-
255
- `npx keiko init` relies on the project-local binary created by installing
256
- `@oscharko-dev/keiko`. Do not use `npx keiko init` as a standalone registry
257
- command in a fresh project, because `keiko` is the binary name, not the npm
258
- package name.
259
-
260
- Open the local UI:
261
-
262
- ```text
263
- http://127.0.0.1:1983
264
- ```
265
-
266
- Stop Keiko when you are done:
267
-
268
- ```bash
269
- npm run keiko:stop
270
- ```
271
-
272
- `keiko init` adds these local scripts to `package.json`:
273
-
274
- | Script | Purpose |
275
- | --------------------- | ---------------------------------------------- |
276
- | `npm run keiko:start` | Starts the local Keiko UI on the default port. |
277
- | `npm run keiko:stop` | Stops the local Keiko UI process. |
278
-
279
- These scripts call the installed package entry by relative path, so they do not depend on a
280
- global `keiko` already on `PATH`. This avoids stale-version launches when a machine still has an
281
- older global install on macOS or Windows.
282
-
283
- ## First-run setup
284
-
285
- If no model gateway is configured, the UI asks for:
286
-
287
- - Base URL, for example `https://llm-gateway.example.com/v1`
288
- - API token
289
- - Optional API-key header, only when your gateway admin provides a custom header
290
- - Deployment names, only when the gateway cannot expose a reliable model list
291
-
292
- Keiko calls the gateway model list endpoint, tests discovered chat models with a small chat-completions request, and stores only callable chat models in the local runtime configuration. LiteLLM-compatible gateways can also provide model metadata that lets Keiko filter non-chat models before testing. Credentials stay on the local machine and are not returned to the browser.
293
-
294
- For OpenAI-compatible gateways such as LiteLLM, usually leave deployment names empty. For Azure AI Foundry, paste the deployment names you want Keiko to offer in the UI.
295
-
296
- The UI runs on loopback only. The `--host` option can validate a loopback host value; the server always binds `127.0.0.1`.
297
-
298
- ## Core workflows
299
-
300
- ### Daily use
301
-
302
- 1. Add a local project path.
303
- 2. Select one of the configured chat models.
304
- 3. For coding agents, select **Ask for approval**, **Supervised workspace**, or **Full access** and confirm
305
- the bounded task and Authority Envelope.
306
- 4. Use chat or a workflow: Generate Tests, Investigate Bug, Explain Plan, or Verify.
307
- 5. Review policy-required or workflow-presented diffs before accepting them; inspect directly applied
308
- agent changes in the Changes and recent-agent-actions surfaces before delivery.
309
- 6. Keep generated evidence with the project review material when required by your delivery process.
310
-
311
- Surface coverage is intentionally not identical. The UI is the primary surface for day-to-day use; the CLI remains available for focused inspection, verification, and automation.
312
-
313
- ### CLI essentials
314
-
315
- | Command | Purpose |
316
- | ----------------------------- | ---------------------------------------------------------------- |
317
- | `keiko init` | Adds local start and stop scripts. |
318
- | `keiko start` | Starts the local UI in the background. |
319
- | `keiko stop` | Stops the local UI. |
320
- | `keiko status` | Prints the local UI status. |
321
- | `keiko ui` | Runs the UI in the foreground. Port to bind (default: 1983). |
322
- | `keiko models validate` | Validates gateway configuration. |
323
- | `keiko context` | Prints a redacted workspace context summary. |
324
- | `keiko gen-tests` | Generates a reviewable unit-test patch. |
325
- | `keiko investigate` | Investigates a bug and proposes a fix plus regression test. |
326
- | `keiko verify` | Runs configured verification gates and writes redacted evidence. |
327
- | `keiko evidence list` | Lists local evidence manifests. |
328
- | `keiko evidence show <runId>` | Shows one redacted evidence manifest. |
329
- | `keiko doctor` | Diagnoses stale global-vs-local launch paths. |
330
- | `keiko repair` | Runs an offline diagnostic-and-repair pass on the local install. |
331
- | `keiko uninstall` | Removes Keiko's runtime artifacts so you can reinstall cleanly. |
332
- | `keiko update status` | Prints governed update status for support/headless workflows. |
333
- | `keiko update check` | Runs a fresh governed update availability check. |
334
- | `keiko update apply` | Applies an update only when policy and install mode allow it. |
335
-
336
- `keiko gen-tests` and `keiko investigate` print a reviewable report but do not persist an evidence manifest. Use `keiko run`, `keiko verify`, or the UI evidence view when a stored manifest is required.
337
-
338
- ### Governed updates
339
-
340
- The in-app update window is the primary update path for ordinary users. The
341
- `keiko update` CLI is a secondary support surface for headless environments and
342
- support transcripts:
343
-
344
- ```bash
345
- keiko update status # cached/startup-style status: current version, target, policy, install mode
346
- keiko update check # fresh registry/release-impact check
347
- keiko update apply # package mutation only when policy and install-mode gates allow it
348
- ```
349
-
350
- `keiko update apply` uses the same governed backend update authority as the UI.
351
- It refuses policy-disabled, unsupported, transient, linked, local-checkout, or
352
- ambiguous install modes and prints manual instructions instead of guessing a
353
- package-manager command. CLI output is support-oriented: it reports release
354
- availability, affected state stores, required remediation, policy state, and
355
- manual next steps, but does not print raw package-manager logs, private install
356
- paths, prompts, model output, customer content, or secret-bearing environment
357
- values.
358
-
359
- ### Repair and uninstall
360
-
361
- `keiko repair` runs an offline, deterministic pass that fixes a broken or half-installed local state without a full reinstall. It removes a stale `ui.pid` left by an unclean shutdown, tightens the `.keiko` state-directory permissions to `0o700`, and normalizes the permissions of every known Keiko-owned runtime artifact under it — the UI, Memory, and Local-Knowledge databases and their `-wal`/`-shm` sidecars, Evidence and Quality-Intelligence records, and the sealed credential vaults — to owner-only `0o700`/`0o600` on POSIX. It also prunes launcher records whose shortcut files were deleted, verifies the built CLI/UI assets, the launch path, and any configured model-gateway file, and flags lingering plaintext credentials left in the config by an interrupted migration. The audit is content-free: it reports paths and categories, never file contents, and never touches a customer file that merely lives under `.keiko`. Items it cannot fix automatically are listed as `action`. Add `--dry-run` to report without changing anything.
362
-
363
- On Windows, POSIX modes do not apply; repair reports that NTFS ACLs govern access rather than pretending an equivalent change was made.
364
-
365
- ```bash
366
- keiko repair # diagnose and repair in place
367
- keiko repair --dry-run # report findings only
368
- ```
369
-
370
- To verify (rather than repair) the at-rest posture of a local `.keiko` tree — no plaintext credentials, owner-only modes, encrypted Memory/Local-Knowledge content, and protected Evidence/QI artifacts — run the read-only auditor:
371
-
372
- ```bash
373
- npm run audit:local-state -- --state-dir ~/.keiko # exit 0 healthy, 1 on any finding
374
- ```
375
-
376
- `keiko uninstall` reverses the runtime artifacts Keiko creates on a machine so you can clean your device and reinstall a clean version. It removes the user-local launcher shortcut(s), the `keiko:start` / `keiko:stop` scripts that `keiko init` added to your `package.json` (only when they still match what `init` writes), and Keiko-owned runtime state under `.keiko`. With `--state` (and by default), it removes the manifest of Keiko-owned sensitive artifacts — lifecycle and launcher files, the UI, Memory, and Local-Knowledge databases and their sidecars, Evidence and Quality-Intelligence records, and the sealed credential vaults — and then removes the state directory itself only once nothing of yours remains. A customized script, an unknown (non-Keiko) file under `.keiko`, and any symlink are never touched or followed. With no scope flag all three areas are removed; `--state`, `--launchers`, and `--scripts` narrow the operation, and `--dry-run` previews it.
377
-
378
- `keiko uninstall --state` deletes local Evidence, Memory, and Local-Knowledge stores. Removing a file from the filesystem unlinks it but does not guarantee secure erasure of SSD-backed data. Repair (`diagnose and fix permission drift`) and uninstall (`remove Keiko-owned local runtime artifacts`) are distinct: repair never deletes a store, and uninstall never weakens permissions.
379
-
380
- ```bash
381
- keiko uninstall # remove launcher, scripts, and state
382
- keiko uninstall --dry-run # preview what would be removed
383
- keiko uninstall --state # remove only Keiko-owned runtime state under .keiko
384
- keiko uninstall --launchers # remove only the OS launcher shortcut
385
- ```
386
-
387
- Keiko never removes its own installed npm package — a running process cannot reliably delete the files it is executing from. After `keiko uninstall` completes it prints the package-manager command to finish removal:
388
-
389
- ```bash
390
- npm uninstall -g @oscharko-dev/keiko # global install
391
- npm uninstall @oscharko-dev/keiko # local install in a project
392
- ```
393
-
394
- ### Connected sources: folder search vs. Knowledge Capsules
395
-
396
- Chat and Quality Intelligence can both connect to external knowledge. The connection type determines how content is indexed and searched.
397
-
398
- **Folder and file search (fast, ephemeral):**
399
-
400
- The fast search of connected folders and files loads text-based documents on demand and scans them at request time. It covers plain-text formats only: code, markdown, JSON, CSV, HTML, configuration files, and similar UTF-8 text. Binary detection is content-based (a byte-level probe of each file), not extension-based — binary files, images, and container formats such as PDF and DOCX are skipped by the fast search, never parsed. Files larger than 2 MiB are omitted; the UI displays a coverage notice showing how many files were skipped and why (oversized, binary, unreadable, or corrupt). Corruption does not halt the search — malformed files are skipped and the run continues.
401
-
402
- Use folder search for:
403
-
404
- - Codebases and configuration repositories
405
- - Text-based documentation
406
- - Ad-hoc browsing of a project structure
407
-
408
- **Knowledge Capsules (persistent, indexed):**
409
-
410
- Knowledge Capsules are the right choice for larger, heterogeneous, or long-lived knowledge collections. Documents are parsed into chunks, embedded with vector representations, and indexed persistently in the Keiko workspace. The index survives workspace restarts and can be reused across multiple chats and Quality Intelligence runs without re-parsing. Unlike the fast search, capsules run real document parsers: in addition to the plain-text formats they parse PDF and Office documents (DOCX), plus JSON, CSV, and HTML. Capsules are composed into Capsule Sets for thematic grouping.
411
-
412
- Create a capsule when:
413
-
414
- - You have a stable collection of documents (team handbook, product specs, compliance guides, architectural decisions)
415
- - Content is larger than a few files or contains PDFs and Office documents
416
- - You want to reuse the same knowledge across multiple chats or QI runs
417
- - Semantic search (finding related concepts, not just keyword matches) is valuable
418
-
419
- The effective difference is scope and persistence: folder search is ephemeral and works best for the current project; capsules are permanent and work well for external, domain-specific knowledge that applies across projects.
420
-
421
- ## Install as an app
422
-
423
- After Keiko's UI loads in a Chromium-family browser (Chrome, Edge, or Chromium), an "Install Keiko" affordance appears in the page header. Accepting the prompt installs Keiko as a standalone application with the Keiko icon in your OS application shelf, Dock, or Start menu.
424
-
425
- For an OS shortcut that starts the local server in one step:
426
-
427
- ```bash
428
- keiko launcher install
429
- ```
430
-
431
- This generates a shortcut in `~/.local/share/applications/` (Linux), `~/Applications/` (macOS), or `%APPDATA%\\Microsoft\\Windows\\Start Menu\\Programs\\` (Windows). Remove it with `keiko launcher remove`. Firefox and Safari users can follow the manual fallback instructions in the [PWA installability contract](https://github.com/oscharko-dev/Keiko/blob/dev/docs/pwa-installability-contract.md).
432
-
433
- ## Configuration
434
-
435
- The UI can create a local runtime config during first-run setup. For scripted use, provide a JSON config file through `KEIKO_CONFIG_FILE` or `--config`:
436
-
437
- ```json
438
- {
439
- "providers": [
440
- {
441
- "modelId": "example-chat-model",
442
- "baseUrl": "https://llm-gateway.example.com/v1",
443
- "apiKey": "replace-me",
444
- "apiKeyHeaderName": "authorization"
445
- }
446
- ]
447
- }
448
- ```
449
-
450
- Environment variables can override file values:
451
-
452
- | Variable | Purpose |
453
- | -------------------------------------- | --------------------------------- |
454
- | `KEIKO_CONFIG_FILE` | Path to a gateway config file. |
455
- | `KEIKO_DEFAULT_BASE_URL` | Fallback gateway base URL. |
456
- | `KEIKO_DEFAULT_API_KEY` | Fallback gateway API token. |
457
- | `KEIKO_DEFAULT_API_KEY_HEADER_NAME` | Fallback credential header name. |
458
- | `KEIKO_MODEL_<ID>_BASE_URL` | Per-model base URL override. |
459
- | `KEIKO_MODEL_<ID>_API_KEY` | Per-model API token override. |
460
- | `KEIKO_MODEL_<ID>_API_KEY_HEADER_NAME` | Per-model credential header name. |
461
- | `KEIKO_UI_PORT` | Local UI port override. |
462
-
463
- `KEIKO_*` runtime variables are read from the process environment only. `keiko ui` does not
464
- import them automatically from a repository-local `.env`; use an explicit shell export, process
465
- env-file launch, `--config`, or the first-run setup flow.
466
-
467
- Supported credential headers are `authorization`, `x-litellm-key`, `x-api-key`, and `api-key`.
468
- Keiko maps the provider-neutral output budget to `max_completion_tokens` for GPT-5 and o1/o3/o4
469
- model IDs, and to legacy `max_tokens` otherwise. Providers behind an opaque model alias can set
470
- `outputTokenParameter` explicitly to either wire parameter.
471
-
472
- Do not commit gateway config files, API tokens, `.keiko/`, or evidence that contains project-specific review material unless your process explicitly requires it.
473
-
474
- ### Grounding limits
475
-
476
- Operators can tune how many sources a chat or Quality Intelligence run may connect and how large the retrieved context can be. All fields accept positive integers; values above the hard ceiling are clamped silently.
477
-
478
- Add a `grounding` block to `keiko.config.json`:
479
-
480
- ```json
481
- {
482
- "providers": [{ "...": "..." }],
483
- "grounding": {
484
- "maxConnectedSources": 8,
485
- "hybridMaxExcerptBytes": 65536
486
- }
487
- }
488
- ```
489
-
490
- Environment variables override file config. Each variable maps to the matching field via `KEIKO_GROUNDING_` + the field name in SCREAMING_SNAKE_CASE:
491
-
492
- | Variable | Field | Default | Hard ceiling |
493
- | --------------------------------------------- | -------------------------- | ------- | ------------ |
494
- | `KEIKO_GROUNDING_MAX_CONNECTED_SOURCES` | `maxConnectedSources` | 16 | 64 |
495
- | `KEIKO_GROUNDING_MAX_LOCAL_KNOWLEDGE_SOURCES` | `maxLocalKnowledgeSources` | 16 | 64 |
496
- | `KEIKO_GROUNDING_MAX_PROMPT_REFERENCES` | `maxPromptReferences` | 16 | 64 |
497
- | `KEIKO_GROUNDING_MAX_EXCERPT_CHARS` | `maxExcerptChars` | 900 | 20 000 |
498
- | `KEIKO_GROUNDING_REFERENCE_BUDGET` | `referenceBudget` | 10 | 256 |
499
- | `KEIKO_GROUNDING_HYBRID_MAX_CANDIDATES` | `hybridMaxCandidates` | 100 | 256 |
500
- | `KEIKO_GROUNDING_HYBRID_MAX_EXCERPT_BYTES` | `hybridMaxExcerptBytes` | 131 072 | 524 288 |
501
-
502
- `maxConnectedSources` bounds the number of folder/file scope entries per chat. `maxLocalKnowledgeSources` bounds the number of Knowledge Capsule or Capsule Set bindings per chat.
503
-
504
- On top of the per-list bounds, a single combined cap of `max(maxConnectedSources, maxLocalKnowledgeSources)` — default 16 — applies across all connected source kinds together (folders, files, repositories, and knowledge connectors). This combined cap is enforced everywhere a source is connected: a Chat PATCH that would exceed it is rejected with HTTP 400, the workspace connect gesture shows a visible "source limit reached" notice instead of binding, and Quality Intelligence drops over-cap run sources with a coverage notice. Workspace connection edges are drawn only after the chat binding is accepted; unavailable sources or failed persistence show a concise connection notice and do not leave a dangling visual edge. Chats that already exceed the cap (rows written under a higher prior operator config) may keep or shrink their existing sources but cannot grow; at ask time only the first 16 sources per kind are explored and the rest surface as skipped-source notices.
505
-
506
- The effective limits at runtime are visible via `GET /api/config` as `effectiveGroundingLimits`.
507
-
508
- ### Optional RAG reranker
509
-
510
- Local Knowledge and hybrid grounded answers can use an optional Cohere-compatible cross-encoder
511
- reranker after the broad retrieval/RRF candidate pass and before prompt assembly. The intended
512
- deployment is a self-hosted LiteLLM-compatible gateway exposing `/v1/rerank`, for example a
513
- Qwen3-reranker model served behind Infinity or vLLM and fronted by LiteLLM.
514
-
515
- Add a top-level `reranker` block to `keiko.config.json`:
516
-
517
- ```json
518
- {
519
- "providers": [{ "...": "..." }],
520
- "reranker": {
521
- "modelId": "qwen3-reranker",
522
- "baseUrl": "https://litellm.internal.example/v1",
523
- "apiKeySecretRef": "model-gateway:reranker",
524
- "apiKeyHeaderName": "authorization",
525
- "timeoutMs": 30000
526
- }
527
- }
528
- ```
529
-
530
- Keiko sends this request shape to `${baseUrl}/rerank`:
531
-
532
- ```json
533
- {
534
- "model": "qwen3-reranker",
535
- "query": "user question",
536
- "documents": ["retrieved excerpt", "retrieved excerpt"],
537
- "top_n": 16
538
- }
539
- ```
540
-
541
- Environment variables override the file block:
542
-
543
- | Variable | Purpose |
544
- | ------------------------------------ | ---------------------------------- |
545
- | `KEIKO_RERANKER_MODEL_ID` | Reranker model/deployment id. |
546
- | `KEIKO_RERANKER_BASE_URL` | LiteLLM-compatible `/v1` base URL. |
547
- | `KEIKO_RERANKER_API_KEY` | Reranker gateway token. |
548
- | `KEIKO_RERANKER_API_KEY_HEADER_NAME` | Credential header name. |
549
- | `KEIKO_RERANKER_TIMEOUT_MS` | Per-rerank request timeout. |
550
-
551
- When the block is missing, the request times out, the endpoint returns an unsupported response, or
552
- the model endpoint is unavailable, grounded answers fall back to the existing retrieval order and
553
- expose content-free diagnostics (`disabled`, `unavailable`, `invalid-response`, or `applied`).
554
- Queries, excerpts, endpoint URLs, provider payloads, and credentials are not returned in diagnostics.
555
-
556
- ### Figma snapshot connector
557
-
558
- The Figma connector needs exactly one credential: a read-only personal access token with
559
- `file_content:read` scope.
560
-
561
- | Variable | Purpose | Default |
562
- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
563
- | `FIGMA_ACCESS_TOKEN` | Read-only Figma PAT. Loaded from the local `.env` (the only name the UI imports from a repo-local `.env`) or the process environment; consumed server-side only, never sent to the browser, never persisted in snapshots. | — |
564
- | `KEIKO_FIGMA_KEY` | Override for the encrypted vault key name used to store the PAT. | — |
565
- | `KEIKO_FIGMA_PAGE_DEPTH` | Per-screen BFS discovery depth of the scoped deep fetch. | 8 |
566
- | `KEIKO_FIGMA_MAX_NODES_PER_SCREEN` | Node budget per screen before the branch stays shallow. | 10000 |
567
- | `KEIKO_FIGMA_MAX_FETCHES_PER_SCREEN` | Scoped API fetch budget per screen. | 32 |
568
- | `KEIKO_FIGMA_MAX_SCREENS_DEEP` | Maximum screens that are deep-fetched per snapshot. | 80 |
569
- | `KEIKO_FIGMA_FETCH_CONCURRENCY` | Concurrent Figma API fetches during the snapshot build. | 3 |
570
- | `KEIKO_FIGMA_REQUEST_TIMEOUT_MS` | Per-request timeout for Figma API and render downloads. | 60000 |
571
- | `KEIKO_FIGMA_BUILD_DEADLINE_MS` | Total wall-clock deadline for one snapshot build (HTTP 504 `FIGMA_BUILD_TIMEOUT` when exceeded). | 600000 |
572
-
573
- Pagination values accept positive integers; values above the hard safety ceilings are clamped: `pageDepth` 16, `maxNodesPerScreen` 50000, `maxFetchesPerScreen` 128, `maxScreensDeep` 250, `fetchConcurrency` 8.
574
-
575
- Figma is contacted only during the bounded snapshot build (scoped node fetch + screen render); every downstream stage — Quality Intelligence test generation, the accessibility baseline, design-to-code — reads the stored immutable snapshot. Re-snapshot is an explicit full re-fetch. Concurrent snapshot requests for the same board coalesce into one build. Budget caps surface as coverage notices in the snapshot summary, never as silent truncation. Failures are coded (`FIGMA_RATE_LIMITED`, `FIGMA_NETWORK_UNREACHABLE`, `FIGMA_EGRESS_TIMEOUT`, `FIGMA_TLS_CA_FAILURE`, `FIGMA_PROXY_*` — proxy codes appear only when a proxy is actually configured) and content-free: no URL, host, or token material ever appears in an error.
576
-
577
- ### Outbound egress (proxy / custom CA)
578
-
579
- Keiko routes Figma and model-gateway egress through one shared outbound HTTP layer with forward-proxy and custom-CA support. Configure it with an `egress` block in `keiko.config.json` and/or environment variables (the `KEIKO_*` form wins over the standard form):
580
-
581
- ```json
582
- {
583
- "providers": [{ "...": "..." }],
584
- "egress": {
585
- "httpsProxy": "http://proxy.corp.example:8080",
586
- "noProxy": "localhost,127.0.0.1,.internal.example",
587
- "caBundlePath": "/etc/ssl/corp-root-ca.pem"
588
- }
589
- }
590
- ```
591
-
592
- | Variable | Purpose |
593
- | ----------------------------------- | ------------------------------------------------------ |
594
- | `KEIKO_HTTPS_PROXY` / `HTTPS_PROXY` | Forward proxy for https egress (CONNECT tunnel). |
595
- | `KEIKO_HTTP_PROXY` / `HTTP_PROXY` | Forward proxy for http egress. |
596
- | `KEIKO_NO_PROXY` / `NO_PROXY` | Bypass list (`*`, exact host, `.suffix`, `host:port`). |
597
- | `KEIKO_CA_BUNDLE_PATH` | PEM bundle for TLS-intercepting proxies / private CAs. |
598
-
599
- Trusted CAs compose from Node's bundled roots, the operating-system trust store (macOS keychain via `tls.getCACertificates`), `NODE_EXTRA_CA_CERTS`, and `caBundlePath` — in many corporate-CA environments the system trust store alone is sufficient and no configuration is needed. Proxy URLs must not embed credentials; a malformed egress variable is reported by name (the remaining egress fields stay effective — one bad variable cannot silently disable the proxy). A configured-but-unreadable CA bundle logs a warning instead of failing silently.
600
-
601
- ## Security boundaries
602
-
603
- Keiko is a local tool, not a remote service.
604
-
605
- - The UI binds to `127.0.0.1`.
606
- - API keys are accepted from local config, local environment, or the first-run UI flow.
607
- - Local config stores **secret references, not secret values**: provider API keys and the Figma token are sealed in per-feature AES-256-GCM vaults, and `keiko.config.json` carries only non-secret metadata and stable `apiKeySecretRef` references ([ADR-0046](https://github.com/oscharko-dev/Keiko/blob/dev/docs/adr/ADR-0046-local-credential-vault.md)).
608
- - Memory Vault ([ADR-0035](https://github.com/oscharko-dev/Keiko/blob/dev/docs/adr/ADR-0035-memory-vault-encryption-at-rest.md)) and Local Knowledge ([ADR-0047](https://github.com/oscharko-dev/Keiko/blob/dev/docs/adr/ADR-0047-local-knowledge-content-encryption.md)) configured content columns are encrypted at rest. Local Knowledge keeps a plaintext lexical FTS projection for local fallback retrieval; the local-state auditor treats that projection as reconstructive residual data and scans it for secret-shaped material.
609
- - Credentials are redacted from logs, evidence, and browser responses.
610
- - Workspace reads are bounded by the selected local project path.
611
- - Commands are allowlisted and run without a shell.
612
- - Generated patches enter governed preflight. Review is required when the shared mode/resource/risk
613
- policy returns `approval-required`; policy-allowed patches may apply inside a validated Authority
614
- Envelope without another prompt. Delivery remains separately human-approved.
615
- - Evidence is redacted before it is written, stored owner-only, and bounded by deterministic retention.
616
-
617
- The full per-surface posture — distinguishing file permissions, redaction, encryption, retention, and tamper evidence as independent controls — is the [local runtime-state contract](https://github.com/oscharko-dev/Keiko/blob/dev/docs/local-runtime-state-contract.md). A deterministic auditor (`npm run audit:local-state -- --state-dir <path>`) checks a real `.keiko` tree against it.
618
-
619
- Known limits:
620
-
621
- - Keiko is not a sandbox or OS-level isolation layer.
622
- - Local encryption protects data **at rest**. It does not protect against malware running as the same user, a live compromised Keiko process, or a stolen machine on which the OS keychain is already unlocked — while a store is open its content is decrypted in process memory by necessity. The keyfile key tier stores the key beside the data; regulated deployments should prefer an injected `KEIKO_*_KEY` or the OS keychain.
623
- - Workflow evidence files are ordinary local files. Quality Intelligence run manifests carry SHA-256 integrity hashes verified on read (tamper-evident, not tamper-proof). Customer-reconstructive evidence artifacts are not yet encrypted at rest — owner-only permissions, redaction, and bounded retention are the compensating controls ([ADR-0048](https://github.com/oscharko-dev/Keiko/blob/dev/docs/adr/ADR-0048-evidence-artifact-confidentiality.md)).
624
- - Cleartext metadata leaks the shape of stored data (how much, which scopes, when). Local Knowledge's plaintext lexical FTS projection can also reveal normalized indexed terms; see the runtime-state contract before using it for regulated corpora.
625
- - Local project scripts can execute repository code when you run verification.
626
- - Do not run Keiko against untrusted repositories.
627
-
628
- ## Privacy and evidence
629
-
630
- Every grounded answer in the Conversation Center shows a context inspection summary so you can see which scope was searched and how much budget was spent. The connected context pack itself is ephemeral and never persisted, while evidence runs survive chat deletion intentionally for audit.
631
-
632
- Read the full contracts and decisions:
633
-
634
- - [Connected context privacy contract](https://github.com/oscharko-dev/Keiko/blob/dev/docs/connected-context-privacy.md)
635
- - [Conversation Center privacy and retention](https://github.com/oscharko-dev/Keiko/blob/dev/docs/conversation-center-privacy.md)
636
- - [ADR-0022: Connected context privacy](https://github.com/oscharko-dev/Keiko/blob/dev/docs/adr/ADR-0022-connected-context-privacy.md)
637
-
638
- ## Troubleshooting
639
-
640
- | Symptom | Check |
641
- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
642
- | UI does not open | Run `npx keiko status`, then inspect `.keiko/ui.log`. |
643
- | Port is busy | Start with `KEIKO_UI_PORT=1984 npm run keiko:start` or stop the process using the port. |
644
- | PowerShell blocks npm | Run `npm.cmd run dev:start` when `npm.ps1` is blocked by the local execution policy. |
645
- | No model appears | Reopen Settings, verify the base URL and token, then run the credential test again. |
646
- | Credential test fails | Confirm the gateway accepts OpenAI-compatible chat-completions requests at the configured base URL. |
647
- | Custom proxy key fails | Confirm whether your gateway expects `Authorization` or a custom API-key header such as `X-Litellm-Key`. |
648
- | Stale process state | Run `npm run keiko:stop`, then `npx keiko repair` from a project where `@oscharko-dev/keiko` is installed to clear a stale pid and verify the install. |
649
- | Broken local install | Run `npx keiko repair` for an offline diagnostic-and-repair pass, or `npx keiko uninstall` to reset. |
650
-
651
- For categorized playbooks covering TLS trust, first-run gateway setup, `NO_MODEL`, workspace path validation, and run-engine command denials, see the [Troubleshooting guide](https://github.com/oscharko-dev/Keiko/blob/dev/docs/troubleshooting/README.md).
652
-
653
- ## Repository notes
654
-
655
- This repository already carries several strong open-source engineering patterns worth preserving and extending:
656
-
657
- - Monorepo package boundaries enforced through dependency-cruiser and import-policy checks
658
- - Required `ci`, CodeQL, dependency review, pinned-action SHA checks, SBOM generation, and supply-chain gates
659
- - Explicit security and audit boundaries in the product and in the workflow design
660
- - Installability, smoke, and verification-oriented scripts for release discipline
661
-
662
- When you contribute, prefer extending an existing package or workflow over introducing a parallel implementation. The ADR set, package graph checks, and import-policy checks are part of the repository contract, not optional documentation.
109
+ Node.js 24.18 LTS and npm 11.16 for the npm path — the desktop packages bring their own runtime.
663
110
 
664
- ## Further reading
111
+ ## Learn more
665
112
 
666
- - [Local UI guide](https://github.com/oscharko-dev/Keiko/blob/dev/docs/ui-runbook.md)
667
- - [Security and audit boundaries](https://github.com/oscharko-dev/Keiko/blob/dev/docs/security-and-audit-boundaries.md)
668
- - [Troubleshooting guide](https://github.com/oscharko-dev/Keiko/blob/dev/docs/troubleshooting/README.md)
669
- - [Pilot guide](https://github.com/oscharko-dev/Keiko/blob/dev/docs/pilot/runbook.md)
670
- - [Pilot evaluation](https://github.com/oscharko-dev/Keiko/blob/dev/docs/pilot/go-no-go.md)
671
- - [Contributing guide](CONTRIBUTING.md)
672
- - [Security policy](SECURITY.md)
113
+ - [Documentation](https://github.com/oscharko-dev/Keiko/tree/dev/docs) — architecture decisions, design system, troubleshooting
114
+ - [Contributing](https://github.com/oscharko-dev/Keiko/blob/dev/CONTRIBUTING.md) — the quality bar and how changes land
115
+ - [Security policy](https://github.com/oscharko-dev/Keiko/blob/dev/SECURITY.md) — reporting and boundaries
116
+ - [Report a finding](https://github.com/oscharko-dev/Keiko/blob/dev/docs/user-finding-report.md) — structured, account-free intake
673
117
 
674
118
  ## License
675
119
 
676
- Apache-2.0. See `LICENSE`, `NOTICE`, and `TRADEMARKS.md`.
120
+ [Apache 2.0](https://github.com/oscharko-dev/Keiko/blob/dev/LICENSE) — © Oliver Scharkowski