hokkoro 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# Hokkoro
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A cozy painted village where your AI agents are the villagers. You walk around (or work from desk mode), give
+villagers jobs, approve what they want to do, and read what they deliver as letters. Build a workshop on a plot and a
+new villager moves in. Early access.
+
+## Play
+
+You need Node 20.11 or newer. In a terminal:
+
+```bash
+npx hokkoro
+```
+
+Your village opens in the browser. Keep the terminal open while you play. Without a key the villagers act it out (demo
+mode); to make them work for real, open Connect in the village and paste an Anthropic API key. Your village (keys,
+residents, workshops, the library, downloaded models) stays on your computer in `~/.hokkoro`. Another port:
+`PORT=8788 npx hokkoro`.
+
+## Develop
+
+```bash
+cp .env.example .env     # then put an ANTHROPIC_API_KEY in it
+npm install
+npm run dev              # server on :8787, client on :5173
+```
+
+Open http://localhost:5173. WASD or arrows to move, click to walk, E to interact, Esc to close a panel.
+
+Release for players: bump `version` in package.json, then `npm run release` (builds, uploads new models to the R2
+bucket hokkoro-assets under their content hash, publishes the app without models to npm as `hokkoro`).
+
+## What is where
+
+- `server/harness/npcs.js` the villagers: persona, look, home, workshop. Add one here and it appears in the world.
+- `server/harness/tools.js` what villagers can do: say, notebook, ask the player, deliver, message another villager, and
+  for the ranger fetch_url (needs the player's approval each time) and dns_lookup.
+- `server/harness/runner.js` one villager turn: a manual tool-use loop on the Anthropic SDK, adaptive thinking, effort
+  from `VILLAGE_EFFORT`, prompt caching on the system block.
+- `server/harness/village.js` the state and the orchestration: the Mayor assigns a quest, assignees run in parallel,
+  villagers can ask each other (two hops max), talks keep a short memory per villager, every change is an event.
+- `server/index.js` Express + WebSocket. In production it also serves `dist/`.
+- `client/src/world.js` the village meshes. `npc.js` a villager (placeholder body from `look`, swapped for
+  `public/models/<id>.glb` when present), name tag, speech bubble, walking. `ui.js` the panels. `main.js` scene,
+  camera, player, input.
+
+## Models for the villagers
+
+Export a GLB per villager (Tripo or anything else) to `client/public/models/<id>.glb` with id one of `mayor`, `scribe`,
+`ranger`, `tinker`, `bard`. It is scaled to 1.7 units tall and placed on the ground. Reload the page.
+
+## Cost
+
+Every quest is a few model calls (the Mayor, each assignee, any relay). The status line at the top left shows calls and
+tokens for the session. `VILLAGE_MODEL=claude-haiku-5-5` is the cheap setting while iterating on the world.

package/bin/hokkoro.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// `npx hokkoro`: start your village on this computer and open it in the browser. Your village (keys, residents,
+// workshops, the library, the downloaded models) lives in ~/.hokkoro, or HOKKORO_HOME; PORT picks another port.
+import os from 'node:os';
+import path from 'node:path';
+
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (major < 20 || (major === 20 && minor < 11)) {
+  console.error(`Hokkoro needs Node 20.11 or newer (this is ${process.versions.node}). Get it at https://nodejs.org`);
+  process.exit(1);
+}
+
+process.env.NODE_ENV = 'production';
+process.env.VILLAGE_DATA ||= process.env.HOKKORO_HOME || path.join(os.homedir(), '.hokkoro');
+process.env.VILLAGE_OPEN ??= '1';
+await import('../server/index.js');

package/dist/assets/browser-C5uuMlgA.js

@@ -0,0 +1 @@
+import{g as c}from"./index-Bd-W7RaG.js";function f(t,i){for(var o=0;o<i.length;o++){const e=i[o];if(typeof e!="string"&&!Array.isArray(e)){for(const r in e)if(r!=="default"&&!(r in t)){const s=Object.getOwnPropertyDescriptor(e,r);s&&Object.defineProperty(t,r,s.get?s:{enumerable:!0,get:()=>e[r]})}}}return Object.freeze(Object.defineProperty(t,Symbol.toStringTag,{value:"Module"}))}var n,a;function b(){return a||(a=1,n=function(){throw new Error("ws does not work in the browser. Browser clients must use the native WebSocket object")}),n}var u=b();const w=c(u),p=f({__proto__:null,default:w},[u]);export{p as b};