Update flake to enable local server running

AGENTS.md

@@ -0,0 +1,109 @@
+# AGENTS.md
+
+## Purpose
+This repository is a RuneScape bot creation environment. Agents in this repo must produce reliable, long-running automation scripts using the local SDK.
+
+## Canonical Data Sources
+- RuneScape game/reference data is in `./runescape-data`.
+- SDK architecture and behavior references:
+  - `sdk/README.md`
+  - `sdk/API.md`
+  - `sdk/SDK_DESIGN.md`
+  - `scripts/script_best_practices.md`
+
+## Script Location Rules
+- All new reusable scripts and helpers must live in `./bot-scripts`.
+- Existing scripts in `./scripts` may be referenced for patterns, but new script assets should not be created there.
+- Prefer shared utilities in `./bot-scripts` over one-off logic duplicated across scripts.
+
+## Bot Configuration Standard
+- For every newly created bot configuration (`bot.env`), set `SERVER=localhost:8888`.
+- Treat any other default server value in new bot setup as incorrect unless explicitly overridden by user instruction.
+
+## SDK Model (Must Follow)
+- `BotSDK` is plumbing: low-level packet-like actions, resolves on ACK.
+- `BotActions` is porcelain: domain-aware actions, resolves on effect completion.
+- Keep game intelligence in script/porcelain logic, not in assumptions about a single linear flow.
+
+## Reliability Requirements (Non-Linear by Default)
+Scripts must never assume the happy path. Every loop must support interruption, recovery, and retries.
+
+### Mandatory checks in long-running scripts
+1. Continuously dismiss blocking UI (level-up dialogs, modal dialogs, shop/bank leftovers).
+2. Re-read state frequently; do not trust stale references to NPC/loc entities.
+3. Use explicit timeouts for each phase and for the whole script.
+4. Detect progress (XP, inventory, position, objective counters) and track last-progress timestamps.
+5. Trigger recovery paths when no progress is detected.
+6. Handle movement failures with retries/fallback movement and re-pathing.
+7. Handle disconnected or missing state (`state == null`, `!inGame`) gracefully.
+8. Fail fast with clear error messages when recovery budget is exhausted.
+
+### Recovery expectations
+- Retry interactions with bounded attempts.
+- Reposition when targets are missing/unreachable.
+- Re-scan nearby entities instead of reusing old IDs/options.
+- Clear unexpected UI before reattempting actions.
+- Abort cleanly on sustained stuckness rather than infinite stalling.
+
+## Reusable Script Baseline
+New scripts in `./bot-scripts` should reuse common helpers for:
+- `sleep` / paced polling
+- bounded retry
+- progress watchdog
+- stuck detection
+- safe walk wrappers
+- dialog/UI clearing loops
+
+## Style Guidelines for Durable Bots
+- Prefer state-based guards over fixed delays.
+- Use tick-aware message checks when reading `gameMessages`.
+- Keep loops idempotent and resumable.
+- Log decisions and recovery events clearly for debugging.
+- Validate prerequisites (items, skills, location) before each phase, not only at startup.
+
+## Definition of Done for Bot Scripts
+A script is not done unless it:
+- survives transient failures without manual intervention,
+- avoids indefinite stalls,
+- exits with explicit reason on unrecoverable states,
+- and can be reused as a component in other `./bot-scripts` flows.
+
+## Flawless Reliability Policy
+- The target for all scripts is flawless long-running operation, not "mostly works".
+- Any observed hiccup (stall, recovery loop failure, missed interaction, desync, or manual babysitting requirement) must trigger immediate follow-up:
+  - first, determine whether the issue should be fixed in `BotSDK`/`BotActions` and patch it when feasible;
+  - otherwise, add a timestamped note in `NOTES.md` with concrete failure symptoms, likely cause, and explicit manual follow-up required.
+- Hiccups must not be normalized as acceptable behavior; they are either patched or explicitly tracked for SDK/API improvement.
+
+## SDK Change Workflow
+- For SDK changes, prefer working in a dedicated git worktree when practical to isolate scope.
+- Use iterative commits only: keep each commit small, reviewable, and focused on a single logical change.
+- Never batch large unrelated SDK edits into one commit.
+- If follow-up fixes are needed, add additional small commits instead of inflating an in-flight change.
+
+## Data Source Policy (Local-First, No Internet)
+- Default to local repository data only (`runescape-data`, SDK docs, local code, and local logs).
+- Do not use internet sources unless explicitly directed by the user for a specific task.
+- If a task appears to require internet data to proceed, treat that as a `CRITICAL` system/data gap:
+  - log it in `NOTES.md` as `CRITICAL`,
+  - describe exactly what local data is missing,
+  - propose the local dataset/tooling change needed to remove internet dependence.
+
+## RuneScape Data Quality Requirements
+- Correct misinformation and fill missing information in `runescape-data` whenever discovered.
+- If instructions reference a world person/place/thing and its position is unknown, resolve it and add structured location data.
+- Required position format for new location facts: `(x, y, z)` plus any relevant context (area, floor/plane meaning, nearby landmarks, prerequisites, interaction notes).
+- Prefer edits that make data reusable by future agents (clear canonical naming, cross-links, and retrieval-friendly structure).
+- When new coordinates or corrections are added, log the update in `NOTES.md` with what changed and why.
+
+## Notes Log Requirements (`NOTES.md`)
+- Maintain and continuously append to `./NOTES.md` during work in this repository.
+- Every entry must be timestamped in UTC ISO-8601 format (example: `2026-02-07T21:56:31Z`).
+- Each timestamped entry must include:
+  - things that are working,
+  - things that are not working,
+  - things that need improvement.
+- If a missing or inadequate Bot SDK API is discovered, add a clearly labeled `CRITICAL` note with:
+  - the exact missing `BotSDK`/`BotActions` API,
+  - why it blocks or degrades script reliability/productivity,
+  - the concrete workflow affected.

BOT_STATUS.md

@@ -0,0 +1,20 @@
+# BOT STATUS
+
+Track each bot's progression and current intent. Update after every run.
+
+## Bot: testtest
+- Last updated: 2026-02-07T22:02:35Z
+- Account stage: Early progression
+- Skills snapshot:
+  - Mining: Unknown
+  - Fishing: Unknown
+  - Cooking: Unknown
+- Current objective: Establish baseline stats and confirm stable automated training loop.
+- Strategic objective: Build toward reliable multi-skill progression with quest prerequisites tracked.
+- Current script/path: `bots/testtest/script.ts` -> `scripts/draynor-fish-cook-bank/script.ts`
+- Current status: Browser launch fixed; runtime progression data not yet captured in this ledger.
+- Blockers:
+  - No recent verified level snapshot stored.
+- Next actions:
+  - Run script session and capture start/end skill deltas.
+  - Record any hiccups and patch/escalate per policy.

GOALS.md

@@ -0,0 +1,18 @@
+# GOALS
+
+This file tracks high-level goals for the stateless loop agent. Every goal should map to one or more task IDs in `TASKS.md`.
+
+## Goal G-001: Build a durable autonomous bot-operations workflow
+- Objective: Maintain reliable processes for planning, execution, recovery, and handoff across stateless runs.
+- Related tasks: `T-001`, `T-002`, `T-003`
+- Status: In Progress
+
+## Goal G-002: Improve SDK/script reliability toward zero-hiccup execution
+- Objective: Identify and eliminate runtime hiccups via SDK/porcelain patches or explicit follow-up tracking.
+- Related tasks: `T-004`, `T-005`
+- Status: In Progress
+
+## Goal G-003: Progress active bots toward explicit account milestones
+- Objective: Track and advance bot skill/quest/equipment goals with clear current state and next action.
+- Related tasks: `T-006`, `T-007`
+- Status: In Progress

NOTES.md

@@ -0,0 +1,60 @@
+# NOTES
+
+## 2026-02-07T21:56:31Z
+- Working: Standing notes file initialized.
+- Not working: N/A yet.
+- Needs improvement: Capture concrete runtime observations after each script/test run.
+- CRITICAL API wishlist: When a bot script surfaces repeated SDK friction, add a timestamped CRITICAL note here with the exact missing BotSDK/BotActions API and the blocking workflow.
+
+## 2026-02-07T21:57:06Z
+- Working:  now documents mandatory  handling (append-only workflow, UTC timestamps, required categories, and CRITICAL SDK API note format).
+- Not working: No automation enforces note quality/format yet.
+- Needs improvement: Add a lightweight lint/check to validate  entry structure in CI.
+
+## 2026-02-07T21:57:11Z
+- Working: AGENTS.md now documents mandatory NOTES.md handling (append-only workflow, UTC timestamps, required categories, and CRITICAL SDK API note format).
+- Not working: No automation enforces note quality/format yet.
+- Needs improvement: Add a lightweight lint/check to validate NOTES.md entry structure in CI.
+
+## 2026-02-07T21:58:51Z
+- Working: AGENTS.md now includes a Flawless Reliability Policy requiring every hiccup to be patched in SDK/porcelain where feasible, or documented for manual follow-up.
+- Not working: No automated detector currently flags hiccups; detection depends on runtime observation and logs.
+- Needs improvement: Add structured hiccup telemetry and an issue template so failures map directly to SDK/API patch candidates.
+- CRITICAL API wishlist: A first-class SDK hiccup-report API (phase, last-progress-ts, recovery-attempt-count, blocking-UI snapshot) would reduce diagnosis time and make automated recovery tuning possible.
+
+## 2026-02-07T22:03:09Z
+- Working: Added persistent loop tracking files GOALS.md, TASKS.md, and BOT_STATUS.md with explicit goal-task linkage and Started/Completed lifecycle fields.
+- Not working: Bot progression values are still mostly unknown until new runs capture verified skill snapshots.
+- Needs improvement: Automate synchronization so each bot run appends deltas to BOT_STATUS.md and links to a TASKS.md update automatically.
+- CRITICAL API wishlist: A single BotSDK API for atomic skill snapshot + quest progress + location state export would reduce bookkeeping errors and make stateless continuation reliable.
+
+## 2026-02-07T22:05:29Z
+- Working: Added SDK commit discipline to AGENTS.md (prefer worktrees for SDK changes and enforce small iterative commits).
+- Not working: No automatic guard currently blocks oversized commits.
+- Needs improvement: Add a pre-commit or CI check that flags unusually large SDK diffs for manual split.
+
+## 2026-02-07T22:16:43Z
+- Working: `runescape-data` is readable and currently symlinked to `../runescape-graph`; directory listing succeeds.
+- Not working: N/A for this check.
+- Needs improvement: Add a startup validation task that asserts required data symlinks/paths exist before bot runs.
+
+## 2026-02-07T22:17:24Z
+- Working: Confirmed local orange dye acquisition path from quest data (Aggie creates red/yellow dyes, then combine to orange).
+- Not working: Item obtain pages are currently generic templates and do not include concrete acquisition steps.
+- Needs improvement: Enrich runescape-data item obtain nodes with explicit ingredient + NPC + coin-cost instructions.
+
+## 2026-02-07T22:18:16Z
+- Working: Added local-first/no-internet policy to AGENTS.md with explicit CRITICAL handling when internet data is needed.
+- Not working: No automatic guard currently prevents accidental internet dependency during task execution.
+- Needs improvement: Add a workflow check that requires documenting local-source provenance before answering data questions.
+- CRITICAL: Requiring internet data for routine gameplay guidance is a system data coverage bug; missing local dataset slices should be identified and backfilled into runescape-data.
+
+## 2026-02-07T22:41:33Z
+- Working: Added runescape-data quality policy to AGENTS.md requiring correction of misinformation and filling missing world data, including mandatory (x, y, z) capture when unknown.
+- Not working: No schema/lint currently enforces coordinate completeness or structured location metadata consistency.
+- Needs improvement: Add a runescape-data validation rule that rejects new/updated world entities lacking canonical name + (x, y, z) + context fields.
+
+## 2026-02-07T22:47:41Z
+- Working: Added Bot Configuration Standard to AGENTS.md requiring SERVER=localhost:8888 for all newly created bots.
+- Not working: Existing bots may still contain non-standard server settings and need audit/remediation.
+- Needs improvement: Add a bot creation/check script that enforces SERVER=localhost:8888 in new bot.env files automatically.

TASKS.md

@@ -0,0 +1,97 @@
+# TASKS
+
+Every task must be documented extensively and include explicit `Started` / `Completed` fields.
+Use `Completed: No` for ongoing work and `Completed: Yes` only when fully done.
+
+## T-001: Define persistent loop bookkeeping files
+- Goal: `G-001`
+- Started: 2026-02-07T22:02:35Z
+- Completed: Yes
+- Summary: Create durable files that survive stateless runs and preserve operational continuity.
+- Scope:
+  - Establish high-level goals file.
+  - Establish detailed tasks file.
+  - Establish bot status ledger for account progression.
+- Implementation details:
+  - Added `GOALS.md` for high-level objectives and task linkage.
+  - Added `TASKS.md` for detailed execution tracking with explicit lifecycle fields.
+  - Added `BOT_STATUS.md` for per-bot progression snapshots.
+- Validation:
+  - Files created in repository root and ready for iterative updates.
+- Next actions:
+  - Keep all future work mapped to a task and linked to a goal.
+
+## T-002: Enforce task lifecycle discipline for stateless runs
+- Goal: `G-001`
+- Started: 2026-02-07T22:02:35Z
+- Completed: No
+- Summary: Ensure every future activity is represented by a task with unambiguous progress state.
+- Scope:
+  - Record all new initiatives before execution.
+  - Update task notes during and after execution.
+  - Mark completion only when validated outcomes are achieved.
+- Operational policy:
+  - No free-form work outside `TASKS.md`.
+  - If interrupted, resume by reading open tasks where `Completed: No`.
+- Risks:
+  - Drift if updates are skipped during fast iteration.
+- Mitigation:
+  - Append updates immediately after each meaningful action.
+
+## T-003: Maintain a clear backlog of improvement work
+- Goal: `G-001`
+- Started: 2026-02-07T22:02:35Z
+- Completed: No
+- Summary: Keep pipeline of next actions visible so loop executions can continue seamlessly.
+- Scope:
+  - Capture blockers, dependencies, and sequencing.
+  - Keep tasks granular enough to be actionable in one session.
+- Current backlog seeds:
+  - Add notes/task format linting.
+  - Add reliability telemetry checklist.
+
+## T-004: Triage and patch reliability hiccups via SDK/porcelain
+- Goal: `G-002`
+- Started: 2026-02-07T22:02:35Z
+- Completed: No
+- Summary: Any observed runtime hiccup must become either a code patch candidate or explicit tracked follow-up.
+- Scope:
+  - Reproduce hiccups with context.
+  - Assess whether fix belongs in script logic, `BotActions`, or `BotSDK`.
+  - Implement feasible fixes with verification.
+- Escalation path:
+  - If immediate patch is not feasible, log a CRITICAL API gap in `NOTES.md` and create/expand a task.
+
+## T-005: Build reusable reliability helpers in bot-scripts
+- Goal: `G-002`
+- Started: 2026-02-07T22:02:35Z
+- Completed: No
+- Summary: Consolidate retry, watchdog, stuck detection, and safe movement logic into reusable modules.
+- Scope:
+  - Avoid duplicate ad-hoc recovery logic across scripts.
+  - Improve consistency of failure handling and observability.
+- Success criteria:
+  - New/updated scripts depend on shared helpers rather than bespoke loops.
+
+## T-006: Maintain active bot progression ledger
+- Goal: `G-003`
+- Started: 2026-02-07T22:02:35Z
+- Completed: No
+- Summary: Keep per-bot current stats/objectives to support long-horizon goals (skills, quests, unlocks).
+- Scope:
+  - Track current skill levels and current training target.
+  - Track immediate objective and strategic objective.
+  - Track blockers and next run instructions.
+- Data source:
+  - Runtime observations and script outputs.
+
+## T-007: Execute bot goals and update state after each run
+- Goal: `G-003`
+- Started: 2026-02-07T22:02:35Z
+- Completed: No
+- Summary: Run bots toward milestones and update outcomes in `BOT_STATUS.md`, `TASKS.md`, and `NOTES.md`.
+- Scope:
+  - Each run should have a measurable intent and result.
+  - Store outcome deltas (levels gained, quest steps completed, failures).
+- Completion criteria:
+  - Goal-specific milestones reached and verified.