@kohala/devkit 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @kohala/devkit
 
+## 0.1.1 (unreleased)
+
+Bug fixes.
+
+- **Default models updated to match the hosted platform** (BUG-040).
+  Local llm-mode now defaults to `claude-sonnet-4-6` (Anthropic) and
+  `gemini-flash-latest` (Gemini) — the same models the platform runs — so
+  cap tuning and output behaviour carry over after `kohala deploy`. Override
+  locally with `ANTHROPIC_MODEL`, `GEMINI_MODEL`, or `KOHALA_LLM_MODEL`.
+
+- **Default Gemini model changed from `gemini-2.0-flash` to
+  `gemini-flash-latest`** (BUG-041). The previous default hit quota limits
+  on new free-tier Gemini keys; the new default works on fresh keys.
+  Override with `GEMINI_MODEL` or `KOHALA_LLM_MODEL`.
+
+- **`kohala doctor` now correctly distinguishes llm-mode availability from
+  `llm.complete` availability** (BUG-042). `GEMINI_API_KEY` enables
+  `llm.complete` in wrap-mode skills but not the llm-mode tool-use loop
+  (which requires `ANTHROPIC_API_KEY`). The doctor now reports each case
+  separately so the output matches what actually works.
+
+- **`kohala run` error message is now specific when `runtimeMode: "llm"` is
+  used without an Anthropic key** (BUG-042). The previous message suggested
+  that `GEMINI_API_KEY` would work; the new message explains the distinction.
+
+- **`docs/` and `examples/` included in the published tarball** (BUG-034).
+  The README links to both; they now ship inside the package so installed
+  users can read them without cloning the repository.
+
+- **`kohala memory serve` documentation clarified** (BUG-035). The command
+  requires either `--agent <name>` or to be run from inside an agent
+  directory. The docs now show both forms.
+
 ## 0.1.0
 
 Initial release.
@@ -13,3 +46,9 @@ Initial release.
 - Stdlib-only Python script SDK over a loopback RPC boundary
 - Deploy client for the kohala.ai REST API (idempotent, additive,
   `--dry-run`)
+
+### SDK compatibility note (BUG-015)
+
+0.1.0 was released against `@kohala/sdk` 0.1.x. The SDK published 0.2.0 on
+2026-07-20 with updated method signatures. The emulator and deploy client
+work against any SDK version; this note tracks awareness of the divergence.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,37 @@
+# Code of Conduct
+
+## Our pledge
+
+We as members, contributors, and maintainers pledge to make participation in
+the Kohala Devkit project a harassment-free experience for everyone,
+regardless of age, body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the community and the project
+
+Examples of unacceptable behavior:
+
+- Harassment, trolling, insulting or derogatory comments, personal attacks
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers at conduct@kohala.ai. All complaints will be
+reviewed and investigated promptly and fairly. Maintainers are obligated to
+respect the privacy and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to the Kohala Devkit
+
+Thanks for helping! The devkit is deliberately small and boring — please keep
+it that way.
+
+## Setup
+
+```bash
+git clone https://github.com/kohala-ai/devkit
+cd devkit
+npm install         # or pnpm install
+npm run build
+node dist/cli/index.js --version
+```
+
+Python 3 must be on your PATH to run the end-to-end tests.
+
+## Development loop
+
+```bash
+npm run typecheck   # strict tsc, no emit
+npm run lint        # eslint
+npm test            # vitest (unit + CLI e2e)
+npm run build       # tsup -> dist/
+```
+
+## Ground rules
+
+- **Errors fail loudly.** No silent fallbacks, no mock LLM responses, no
+  swallowed exceptions. If something can't work, say so with an actionable
+  message.
+- **Platform parity is the product.** Tool names, manifest fields, cap codes
+  (`PER_RUN_TOKEN_CAP`, `PER_DAY_TOKEN_CAP`, `TOOL_DENIED`), and enforcement
+  order must match the hosted platform. Don't rename things casually.
+- **Dependency budget.** Runtime deps are limited to: commander, zod,
+  @modelcontextprotocol/sdk, execa, picocolors, ora. `pg` stays an optional
+  peer. New runtime dependencies need a strong justification in the PR.
+- **The Python SDK stays stdlib-only.** Scaffolded agents must run without a
+  single `pip install`.
+- Keep CLI command files thin; put behavior in the library modules where it
+  can be unit-tested.
+
+## Submitting changes
+
+1. Fork, branch, make the change, add/adjust tests.
+2. Add a changeset: `npx changeset` (pick patch/minor and write one line).
+3. Open a PR. CI runs typecheck, lint, tests, and build on Node 20 and 22.
+
+## Releases
+
+Releases are automated with [changesets](https://github.com/changesets/changesets):
+merged changesets accumulate, and the release workflow versions, tags, and
+publishes to npm.

package/README.md

@@ -55,9 +55,11 @@ skill scripts).
 ```
 
 - `runtimeMode: "wrap"` executes your script directly and validates its
-  output (stdout).
-- `runtimeMode: "llm"` runs a real tool-use loop against **your own**
-  `ANTHROPIC_API_KEY` — the devkit never mocks completions.
+  output (stdout). Use `llm.complete` from the script SDK to call an LLM
+  mid-script (needs `ANTHROPIC_API_KEY` or `GEMINI_API_KEY`).
+- `runtimeMode: "llm"` runs a real Anthropic tool-use loop — requires
+  `ANTHROPIC_API_KEY`. `GEMINI_API_KEY` works for `llm.complete` in wrap
+  mode but not for this loop. The devkit never mocks completions.
 
 ## Docs
 

package/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Supported versions
+
+Only the latest published version of `@kohala/devkit` receives security
+fixes.
+
+## Reporting a vulnerability
+
+Please email **security@kohala.ai** with a description of the issue, steps to
+reproduce, and the version affected. Do **not** open a public GitHub issue
+for security reports.
+
+We aim to acknowledge reports within 3 business days.
+
+## Scope notes
+
+- The devkit runs agent scripts **you** wrote on **your** machine, with your
+  own credentials. It does not sandbox skill scripts — treat third-party
+  agent code like any other code you execute locally.
+- The `http.post_json` tool refuses private/internal targets: it validates
+  the hostname, every IP it resolves to (IPv4 and IPv6, including
+  IPv4-mapped, link-local, ULA, and CGNAT ranges), and re-validates each
+  redirect hop. A determined attacker with DNS rebinding at request time may
+  still find gaps — do not treat it as a hardened network boundary.
+- `kohala login` stores your API key at `~/.kohala/credentials.json` with
+  mode 600. The `KOHALA_API_KEY` environment variable always takes
+  precedence and is the recommended mechanism in CI.

package/dist/cli/index.js

@@ -725,8 +725,8 @@ var NoLlmKeyError = class extends Error {
     this.name = "NoLlmKeyError";
   }
 };
-var DEFAULT_ANTHROPIC_MODEL = "claude-3-5-haiku-latest";
-var DEFAULT_GEMINI_MODEL = "gemini-2.0-flash";
+var DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-4-6";
+var DEFAULT_GEMINI_MODEL = "gemini-flash-latest";
 function detectLlmProvider(env = process.env) {
   if (env.ANTHROPIC_API_KEY) return "anthropic";
   if (env.GEMINI_API_KEY) return "gemini";
@@ -735,10 +735,12 @@ function detectLlmProvider(env = process.env) {
 async function completeText(prompt, model, maxOutputTokens = 1024, env = process.env) {
   const provider = detectLlmProvider(env);
   if (provider === "anthropic") {
-    return completeAnthropic(prompt, model ?? DEFAULT_ANTHROPIC_MODEL, maxOutputTokens, env);
+    const resolvedModel = model ?? env.KOHALA_LLM_MODEL ?? env.ANTHROPIC_MODEL ?? DEFAULT_ANTHROPIC_MODEL;
+    return completeAnthropic(prompt, resolvedModel, maxOutputTokens, env);
   }
   if (provider === "gemini") {
-    return completeGemini(prompt, model ?? DEFAULT_GEMINI_MODEL, maxOutputTokens, env);
+    const resolvedModel = model ?? env.KOHALA_LLM_MODEL ?? env.GEMINI_MODEL ?? DEFAULT_GEMINI_MODEL;
+    return completeGemini(prompt, resolvedModel, maxOutputTokens, env);
   }
   throw new NoLlmKeyError();
 }
@@ -1211,9 +1213,11 @@ var TOOL_DEFINITIONS = {
 async function runLlmShift(context, skillName, scriptPath, repairFeedback) {
   const apiKey = process.env.ANTHROPIC_API_KEY;
   if (!apiKey) {
-    throw new NoLlmKeyError();
+    throw new Error(
+      'NO_LLM_KEY: llm mode requires ANTHROPIC_API_KEY. GEMINI_API_KEY enables llm.complete calls inside wrap-mode skills, but the llm-mode tool-use loop only supports Anthropic. Set ANTHROPIC_API_KEY in your environment to use runtimeMode: "llm".'
+    );
   }
-  const model = process.env.KOHALA_LLM_MODEL ?? "claude-3-5-haiku-latest";
+  const model = process.env.KOHALA_LLM_MODEL ?? process.env.ANTHROPIC_MODEL ?? "claude-sonnet-4-6";
   const dispatcher = new ToolDispatcher(context);
   const { manifest, meter, trace, runId } = context;
   const tools = Object.entries(TOOL_DEFINITIONS).filter(([name]) => manifest.toolAllowlist.includes(name)).map(([name, definition]) => ({ name: toApiToolName(name), ...definition }));
@@ -2198,8 +2202,15 @@ function registerDoctorCommand(program2) {
       warn("python 3 not found", "wrap-mode `kohala run --local` will not work until installed");
     }
     const provider = detectLlmProvider();
-    if (provider) {
-      ok(`LLM key (${provider})`, "llm.complete and llm mode available");
+    const hasAnthropic = Boolean(process.env.ANTHROPIC_API_KEY);
+    if (hasAnthropic) {
+      ok("LLM key (anthropic)", "llm.complete and llm mode both available");
+    } else if (provider === "gemini") {
+      ok("LLM key (gemini)", "llm.complete available in wrap mode");
+      warn(
+        "no ANTHROPIC_API_KEY",
+        'llm mode (runtimeMode: "llm") requires Anthropic \u2014 GEMINI_API_KEY covers llm.complete only'
+      );
     } else {
       warn(
         "no ANTHROPIC_API_KEY / GEMINI_API_KEY",