feat(02-01): bot workspace scaffold with Env contract (D-09/D-10/D-11/D-15)

- bot/ npm workspace sibling to theme/: grammy ^1.46.0, wrangler ^4.151.3, TS ^5.9.3
- src/config.ts exports Env (BOT_TOKEN, WEBHOOK_SECRET, chat_sessions KVNamespace)
- wrangler.jsonc: main src/webhook.ts + chat_sessions KV binding (id filled in plan 03)
- .gitignore ships .dev.vars/.wrangler/ in the same commit as .dev.vars.example (D-17)
- root delegate scripts bot:test/typecheck/dev/deploy/commands

bot/.dev.vars.example

@@ -0,0 +1,4 @@
+# Copy to .dev.vars and fill for local wrangler dev (D-15). NEVER commit .dev.vars.
+BOT_TOKEN=
+WEBHOOK_SECRET=
+WEBHOOK_URL=

bot/.gitignore

@@ -0,0 +1,2 @@
+.dev.vars
+.wrangler/

bot/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@araharah/bot",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node test/runner.mjs",
+    "typecheck": "tsc --noEmit",
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "commands": "node scripts/register-commands.mjs"
+  },
+  "dependencies": {
+    "grammy": "^1.46.0"
+  },
+  "devDependencies": {
+    "wrangler": "^4.151.3",
+    "typescript": "^5.9.3",
+    "@cloudflare/workers-types": "^5.20261022.1",
+    "@types/node": "^26.6.5"
+  }
+}

bot/src/config.ts

@@ -0,0 +1,8 @@
+// Typed Env contract for the araharah bot Worker (D-10/D-11).
+// Secrets (D-15) are wrangler secrets / .dev.vars mirrors — never committed (D-17).
+
+export interface Env {
+  BOT_TOKEN: string; // wrangler secret (D-15) — Telegram Bot API token from @BotFather
+  WEBHOOK_SECRET: string; // wrangler secret (D-15) — value Telegram echoes in X-Telegram-Bot-Api-Secret-Token
+  chat_sessions: KVNamespace; // TTL-only namespace — first durable KV namespace (PRIV-02)
+}

bot/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "types": ["@cloudflare/workers-types"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"]
+}

bot/wrangler.jsonc

@@ -0,0 +1,7 @@
+{
+  // KV namespace id is filled in plan 03 task 1 after `npx wrangler kv namespace create chat_sessions`
+  "name": "araharah-bot",
+  "main": "src/webhook.ts",
+  "compatibility_date": "2026-10-22",
+  "kv_namespaces": [{ "binding": "chat_sessions", "id": "KV_ID_PLACEHOLDER" }]
+}

package.json

@@ -3,13 +3,19 @@
   "private": true,
   "type": "module",
   "workspaces": [
-    "theme"
+    "theme",
+    "bot"
   ],
   "scripts": {
     "build": "npm run build --workspace theme",
     "sheet": "npm run sheet --workspace theme",
     "gallery": "npm run gallery --workspace theme",
     "audit": "npm run audit --workspace theme",
-    "capture": "npm run capture --workspace theme"
+    "capture": "npm run capture --workspace theme",
+    "bot:test": "npm test -w bot",
+    "bot:typecheck": "npm run typecheck -w bot",
+    "bot:dev": "npm run dev -w bot",
+    "bot:deploy": "npm run deploy -w bot",
+    "bot:commands": "npm run commands -w bot"
   }
 }