Add WallCraft AI MVP scaffolding and documentation

2026-02-06 07:48:40 +00:00
parent cabd4ecf66
commit 34da1bc90b
15 changed files with 524 additions and 0 deletions
--- a/agents.md
+++ b/agents.md
@@ -0,0 +1,236 @@
+WallCraft AI Agents Collaboration Guide for WallCraft AI
+
+Overview
+- Purpose: Define how automated agents will plan, explore, and assist in building a cloud-driven AI workflow for FoundryVTT scene prep (walls, doors, windows), with a safe preview-first workflow.
+- Scope: Plan, explore, and coordinate tasks across agent types; no direct code edits by agents, only plan and guidance unless explicitly executed by humans.
+
+Agent Roles and Responsibilities
+- General Planner (PlanAgent)
+  - Create high-level task plans, decompose features into concrete steps, and assign ownership.
+- Explorer (ExploreAgent)
+  - Inspect repository structure, FoundryVTT APIs, and proposed module architecture.
+- Code Searcher (CodesearchAgent)
+  - Look up API docs, FoundryVTT wall/scene data models, and related examples.
+- Web Scout (WebSearchAgent)
+  - Retrieve current best practices, security considerations, and external docs relevant to cloud AI integration and similar Foundry workflows.
+
+Interaction Protocol
+- Requests and responses are exchanged as structured JSON envelopes.
+- Each task has: task_id, objective, inputs, constraints, and expected outputs.
+- All agents should statically log their actions to an in-app log or a dedicated journal entry for traceability.
+
+Example envelope (high-level)
+- Plan request
+  {
+    "task_id": "plan-001",
+    "role": "Planner",
+    "objective": "Define MVP milestones for AI Prep pipeline",
+    "inputs": { "scope": "FoundryVTT 13.0.351 MVP" },
+    "constraints": { "no destructive edits during planning": true }
+  }
+- Plan response
+  {
+    "status": "ok",
+    "task_id": "plan-001",
+    "plan": [
+      "Create module scaffold with manifest.json",
+      "Implement Settings for cloud endpoint and provider",
+      "Add AI Prep UI (Scene toolbar) and preview layer",
+      "Define payload schema and fixed prompt template",
+      "Implement preview → manual adjust → apply workflow",
+      "Add logging and minimal docs"
+    ],
+    "notes": "Keep MVP strictly non-destructive during preview; apply only after explicit confirmation."
+  }
+
+Task Lifecycle and Phases
+- Phase 0: Planning and scoping
+- Phase 1: MVP scaffolding (module skeleton, settings, UI hooks)
+- Phase 2: Cloud integration and preview rendering
+- Phase 3: Apply flow (convert AI walls to Foundry walls)
+- Phase 4: Safety, validation, and docs
+- Phase 5: Optional enhancements (Doors/Windows refine, per-scene prompts, etc.)
+
+Data Exchange and Contracts (see data-contracts.md)
+- Use a fixed, provider-agnostic payload to cloud AI endpoint
+- Validate AI responses against Foundry grid constraints before enabling apply
+
+Quality and Safety
+- Preview is mandatory before applying changes
+- All actions should be auditable (chat log or journal entry)
+- Validate that walls align to grid and do not collide with tokens
+- Optional data redaction in settings for privacy-sensitive scenes
+
+Documentation and Handoff
+- Produce a short design doc, an API contract summary, and a quick-start guide
+- Maintain change logs for major iterations and provider changes
+
+4) data-contracts.md
+AI Prep Data Contracts (Input to AI, and AI Output)
+
+Input payload to cloud AI
+- Schema (JSON)
+  {
+    "scene": { "id": "scene123", "name": "Test Scene" },
+    "gridSize": 32,
+    "walls": [
+      { "c": [1,1,5,1], "type": "wall", "notes": "outer boundary" },
+      { "c": [5,1,5,5], "type": "door", "notes": "entry" }
+    ],
+    "tokens": [
+      { "id": "tok1", "x": 3, "y": 3, "w": 1, "h": 1 }
+    ],
+    "promptTemplate": "Fixed MVP prompt template string",
+    "providerMetadata": { "providerName": "OpenCodeCloud", "version": "v1" },
+    "previewOnly": true
+  }
+
+AI output payload
+- Schema (JSON)
+  {
+    "walls": [
+      { "c": [1,1,6,1], "type": "wall", "notes": "perimeter suggestion" },
+      { "c": [6,1,6,6], "type": "door", "notes": "future entry" }
+    ],
+    "notes": [ "Preview generated" ],
+    "validationHints": [ "Walls may cross token area; adjust endpoints" ],
+    "previewOnly": true
+  }
+
+Notes
+- All coordinates are grid-aligned integers.
+- Unknown fields from provider can be ignored by the client.
+- If previewOnly is true, apply is disabled until user explicitly enables it.
+
+5) api-contract.md
+Cloud AI Endpoint Contract (example)
+
+Endpoint
+- POST https://api.youraihost.com/ai/map-prep
+
+Headers
+- Authorization: Bearer <apiToken>
+- Content-Type: application/json
+
+Request body (see data-contracts.md)
+- {
+  "scene": { "id": "...", "name": "..." },
+  "gridSize": 32,
+  "walls": [...],
+  "tokens": [...],
+  "promptTemplate": "...",
+  "providerMetadata": { "providerName": "...", "version": "..." },
+  "previewOnly": true
+  }
+
+Response
+- 200 OK
+  - {
+      "walls": [...],
+      "notes": ["Preview generated"],
+      "validationHints": [...],
+      "previewOnly": true
+    }
+- 4xx/5xx responses
+  - { "error": "invalid_payload", "message": "..." }
+  - { "error": "auth_failed", "message": "Invalid API token" }
+
+Security and Privacy
+- Use HTTPS; support short-lived tokens
+- Minimize data; avoid sending unrelated scene data unless required
+- Log access on the server side; provide per-request trace IDs
+
+6) onboarding.md
+Onboarding for WallCraft AI Contributors
+
+Overview
+- This document helps new contributors get up to speed on the WallCraft AI MVP project.
+
+Getting started
+- Prerequisites: FoundryVTT v13.0.351, node environment for building modules, access to cloud AI endpoint
+- Repository layout: modules/wallcraft-ai/ with module.json and src/
+- Key files to know:
+  - module.json: module manifest
+  - src/AIPrep.js: main module entry
+  - src/AIEndpoint.js: HTTP client for cloud AI
+  - src/PreviewLayer.js: canvas overlay logic
+  - src/SettingsPanel.js: UI to configure endpoint/token/provider
+  - src/UIFlow.js: dialog and adjustment UI
+
+Development workflow
+- Plan first: use agents.md to outline tasks
+- Implement in small, testable increments
+- Use non-destructive previews first; require explicit apply
+- Write minimal tests or manual checks for payload shaping and wall conversion
+
+Conventions
+- Naming: consistent with FoundryVTT APIs (Wall, Door, Window, Scene)
+- Data models: grid-aligned coordinates, tokens as bounding boxes
+- Logging: messages go to chat or a dedicated journal entry
+
+Testing and validation
+- Manual test plan: create a sample scene, run AI Prep, verify preview, adjust, apply, verify persistence
+- Edge cases: empty AI response, missing fields, invalid coordinates
+
+Deployment and updates
+- Document how to deploy updates to cloud endpoint if users host their own
+- Provide migration notes for API changes (backward compatibility guidance)
+
+7) glossary.md
+WallCraft AI Glossary
+
+- FoundryVTT: The virtual tabletop platform being extended.
+- Scene: A map/workspace in FoundryVTT where walls, tokens, and other elements live.
+- Wall: A linear obstacle segment; may be solid, a door, or a window.
+- Door/Window: Wall segments with special types; may require swing/hinge data later.
+- GridSize: The pixel size of a single tile on the scene grid.
+- Preview: A non-destructive overlay showing AI-suggested walls before applying them.
+- MVP: Minimum Viable Product.
+- API Token: Secret used to authorize requests to the cloud AI endpoint.
+
+8) quick-start.md
+WallCraft AI Quick Start (MVP)
+
+What you’ll get
+- A cloud-driven FoundryVTT MVP to generate walls (including doors/windows) for the current scene.
+- Non-destructive preview with manual adjustments before applying.
+
+Setup
+- Install FoundryVTT module (WallCraft AI) for FoundryVTT v13.0.351
+- Configure cloud endpoint URL and API token in Settings
+- Ensure the cloud AI endpoint is reachable via HTTPS
+
+How to use
+- In FoundryVTT, open a scene and click the WallCraft AI Prep button in the Scene toolbar
+- The module collects scene data and sends a fixed prompt to the cloud AI
+- See a translucent preview of AI-generated walls
+- Use the adjustment panel to tweak endpoints or types if needed
+- Click Apply to persist walls to the scene
+- Review chat/journal log for traceability
+
+Notes
+- Batching and multi-scene processing are not part of MVP; plan for future sprints if you want to scale.
+- Security: only necessary scene data is sent; token remains with you.
+
+Next steps
+- If you’d like, I can generate concrete starter patches (module.json + a minimal AIPrep.js skeleton and the SettingsPanel), plus the exact payload shapes ready to patch into your repo. I can also tailor naming and endpoint paths to your preferred conventions.
+
+9) structure.md
+WallCraft AI – Default File Structure
+
+- /modules/wallcraft-ai/
+  - module.json
+  - /src/
+    - AIPrep.js
+    - AIEndpoint.js
+    - PreviewLayer.js
+    - SettingsPanel.js
+    - UIFlow.js
+  - /agents.md
+  - /data-contracts.md
+  - /api-contract.md
+  - /onboarding.md
+  - /glossary.md
+  - /quick-start.md
+
+This structure keeps the core module logic separated from the documentation and keeps the docs versioned with the module code.
--- a/api-contract.md
+++ b/api-contract.md
@@ -0,0 +1,36 @@
+Cloud AI Endpoint Contract (example)
+
+Endpoint
+- POST https://api.youraihost.com/ai/map-prep
+
+Headers
+- Authorization: Bearer <apiToken>
+- Content-Type: application/json
+
+Request body (see data-contracts.md)
+- {
+  "scene": { "id": "...", "name": "..." },
+  "gridSize": 32,
+  "walls": [...],
+  "tokens": [...],
+  "promptTemplate": "...",
+  "providerMetadata": { "providerName": "...", "version": "..." },
+  "previewOnly": true
+  }
+
+Response
+- 200 OK
+  - {
+      "walls": [...],
+      "notes": ["Preview generated"],
+      "validationHints": [...],
+      "previewOnly": true
+    }
+- 4xx/5xx responses
+  - { "error": "invalid_payload", "message": "..." }
+  - { "error": "auth_failed", "message": "Invalid API token" }
+
+Security and Privacy
+- Use HTTPS; support short-lived tokens
+- Minimize data; avoid sending unrelated scene data unless required
+- Log access on the server side; provide per-request trace IDs
--- a/data-contracts.md
+++ b/data-contracts.md
@@ -0,0 +1,35 @@
+AI Prep Data Contracts (Input to AI, and AI Output)
+
+Input payload to cloud AI
+- Schema (JSON)
+  {
+    "scene": { "id": "scene123", "name": "Test Scene" },
+    "gridSize": 32,
+    "walls": [
+      { "c": [1,1,5,1], "type": "wall", "notes": "outer boundary" },
+      { "c": [5,1,5,5], "type": "door", "notes": "entry" }
+    ],
+    "tokens": [
+      { "id": "tok1", "x": 3, "y": 3, "w": 1, "h": 1 }
+    ],
+    "promptTemplate": "Fixed MVP prompt template string",
+    "providerMetadata": { "providerName": "OpenCodeCloud", "version": "v1" },
+    "previewOnly": true
+  }
+
+AI output payload
+- Schema (JSON)
+  {
+    "walls": [
+      { "c": [1,1,6,1], "type": "wall", "notes": "perimeter suggestion" },
+      { "c": [6,1,6,6], "type": "door", "notes": "future entry" }
+    ],
+    "notes": [ "Preview generated" ],
+    "validationHints": [ "Walls may cross token area; adjust endpoints" ],
+    "previewOnly": true
+  }
+
+Notes
+- All coordinates are grid-aligned integers.
+- Unknown fields from provider can be ignored by the client.
+- If previewOnly is true, apply is disabled until user explicitly enables it.
--- a/glossary.md
+++ b/glossary.md
@@ -0,0 +1,10 @@
+WallCraft AI Glossary
+
+- FoundryVTT: The virtual tabletop platform being extended.
+- Scene: A map/workspace in FoundryVTT where walls, tokens, and other elements live.
+- Wall: A linear obstacle segment; may be solid, a door, or a window.
+- Door/Window: Wall segments with special types; may require swing/hinge data later.
+- GridSize: The pixel size of a single tile on the scene grid.
+- Preview: A non-destructive overlay showing AI-suggested walls before applying them.
+- MVP: Minimum Viable Product.
+- API Token: Secret used to authorize requests to the cloud AI endpoint.
--- a/module.json
+++ b/module.json
@@ -0,0 +1,19 @@
+{
+  "name": "wallcraft-ai",
+  "title": "WallCraft AI",
+  "description": "Cloud-driven, provider-agnostic AI prep for FoundryVTT scenes (walls including doors and windows) with a safe preview-first workflow.",
+  "version": "0.1.0",
+  "author": "OpenCode",
+  "minimumCoreVersion": "13.0.0",
+  "compatibleCoreVersion": "13.*",
+  "esmodules": true,
+  "scripts": [
+    "src/AIPrep.js",
+    "src/AIEndpoint.js",
+    "src/PreviewLayer.js",
+    "src/SettingsPanel.js",
+    "src/UIFlow.js"
+  ],
+  "url": "https://example.com/wallcraft-ai",
+  "license": "MIT"
+}
--- a/onboarding.md
+++ b/onboarding.md
@@ -0,0 +1,34 @@
+Onboarding for WallCraft AI Contributors
+
+Overview
+- This document helps new contributors get up to speed on the WallCraft AI MVP project.
+
+Getting started
+- Prerequisites: FoundryVTT v13.0.351, node environment for building modules, access to cloud AI endpoint
+- Repository layout: modules/wallcraft-ai/ with module.json and src/
+- Key files to know:
+  - module.json: module manifest
+  - src/AIPrep.js: main module entry
+  - src/AIEndpoint.js: HTTP client for cloud AI
+  - src/PreviewLayer.js: canvas overlay logic
+  - src/SettingsPanel.js: UI to configure endpoint/token/provider
+  - src/UIFlow.js: dialog and adjustment UI
+
+Development workflow
+- Plan first: use agents.md to outline tasks
+- Implement in small, testable increments
+- Use non-destructive previews first; require explicit apply
+- Write minimal tests or manual checks for payload shaping and wall conversion
+
+Conventions
+- Naming: consistent with FoundryVTT APIs (Wall, Door, Window, Scene)
+- Data models: grid-aligned coordinates, tokens as bounding boxes
+- Logging: messages go to chat or a dedicated journal entry
+
+Testing and validation
+- Manual test plan: create a sample scene, run AI Prep, verify preview, adjust, apply, verify persistence
+- Edge cases: empty AI response, missing fields, invalid coordinates
+
+Deployment and updates
+- Document how to deploy updates to cloud endpoint if users host their own
+- Provide migration notes for API changes (backward compatibility guidance)
--- a/progress-todos.json
+++ b/progress-todos.json
@@ -0,0 +1 @@
+[]
--- a/progress.json
+++ b/progress.json
@@ -0,0 +1,12 @@
+[
+  {"id":"t-1","content":"Initialize module skeleton (module.json) and scaffolding","status":"in_progress","priority":"high"},
+  {"id":"t-2","content":"Implement SettingsPanel for endpoint/token/provider","status":"pending","priority":"high"},
+  {"id":"t-3","content":"Implement AIPrep.js to collect scene data and build payload","status":"pending","priority":"high"},
+  {"id":"t-4","content":"Implement AIEndpoint.js to call cloud API and handle responses","status":"pending","priority":"high"},
+  {"id":"t-5","content":"Implement PreviewLayer.js for non-destructive previews","status":"pending","priority":"high"},
+  {"id":"t-6","content":"Implement UIFlow.js to drive MVP flow","status":"pending","priority":"medium"},
+  {"id":"t-7","content":"Wire up Apply logic to convert AI walls to Foundry walls","status":"pending","priority":"high"},
+  {"id":"t-8","content":"Create documentation: quick-start, data/api contracts","status":"pending","priority":"medium"},
+  {"id":"t-9","content":"Add basic tests/manual validation plan","status":"pending","priority":"medium"},
+  {"id":"t-10","content":"Polish error handling, security notes","status":"pending","priority":"low"}
+]
--- a/quick-start.md
+++ b/quick-start.md
@@ -0,0 +1,25 @@
+WallCraft AI Quick Start (MVP)
+
+What you’ll get
+- A cloud-driven FoundryVTT MVP to generate walls (including doors/windows) for the current scene.
+- Non-destructive preview with manual adjustments before applying.
+
+Setup
+- Install FoundryVTT module (WallCraft AI) for FoundryVTT v13.0.351
+- Configure cloud endpoint URL and API token in Settings
+- Ensure the cloud AI endpoint is reachable via HTTPS
+
+How to use
+- In FoundryVTT, open a scene and click the WallCraft AI Prep button in the Scene toolbar
+- The module collects scene data and sends a fixed prompt to the cloud AI
+- See a translucent preview of AI-generated walls
+- Use the adjustment panel to tweak endpoints or types if needed
+- Click Apply to persist walls to the scene
+- Review chat/journal log for traceability
+
+Notes
+- Batching and multi-scene processing are not part of MVP; plan for future sprints if you want to scale.
+- Security: only necessary scene data is sent; token remains with you.
+
+Next steps
+- If you’d like, I can generate concrete starter patches (module.json + a minimal AIPrep.js skeleton and the SettingsPanel), plus the exact payload shapes ready to patch into your repo. I can also tailor naming and endpoint paths to your preferred conventions.
--- a/src/AIEndpoint.js
+++ b/src/AIEndpoint.js
@@ -0,0 +1,16 @@
+// Lightweight HTTP client for the cloud AI endpoint
+export async function aiPrepRequest(payload, endpoint, token) {
+  const resp = await fetch(endpoint, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': token ? `Bearer ${token}` : ''
+    },
+    body: JSON.stringify(payload)
+  });
+  if (!resp.ok) {
+    const err = await resp.text();
+    throw new Error(`AI prep request failed: ${resp.status} ${resp.statusText} - ${err}`);
+  }
+  return resp.json();
+}
--- a/src/AIPrep.js
+++ b/src/AIPrep.js
@@ -0,0 +1,25 @@
+// WallCraft AI: Minimal MVP skeleton for FoundryVTT module (WallCraft AI)
+import { SettingsPanel } from './SettingsPanel.js';
+import { startAIPrepFlow } from './UIFlow.js';
+
+export function initWallCraftAI() {
+  Hooks.on('ready', async function () {
+    if (!game.user?.isGM) return;
+    // Simple guidance dialog for first-time setup
+    new Dialog({
+      title: 'WallCraft AI',
+      content: '<p>WallCraft AI is ready. Use Settings to configure the cloud endpoint, then start the MVP prep flow.</p>',
+      buttons: {
+        settings: { label: 'Settings', callback: () => SettingsPanel.open() },
+        start: { label: 'Start MVP', callback: () => startAIPrepFlow() }
+      },
+      default: 'start'
+    }).render(true);
+  });
+}
+
+Hooks.once('init', () => {
+  // Initialize basic settings with sane defaults if needed
+  // Actual settings are declared in SettingsPanel
+  initWallCraftAI();
+});
--- a/src/PreviewLayer.js
+++ b/src/PreviewLayer.js
@@ -0,0 +1,11 @@
+// Lightweight non-destructive preview layer for WallCraft AI
+export class PreviewLayer {
+  static drawWalls(scene, walls) {
+    // Placeholder: In a full implementation this would render translucent wall overlays
+    console.log('[WallCraft AI] Preview walls:', walls);
+  }
+
+  static clear() {
+    console.log('[WallCraft AI] Clearing previews');
+  }
+}
--- a/src/SettingsPanel.js
+++ b/src/SettingsPanel.js
@@ -0,0 +1,36 @@
+// Settings UI for WallCraft AI (endpoint, token, provider)
+export class SettingsPanel {
+  static open() {
+    const html = `
+      <form id="wca-settings-form">
+        <div>
+          <label>Endpoint URL</label><br/>
+          <input type="text" id="wca-endpoint" style="width:100%" value="https://api.youraihost.com" />
+        </div>
+        <div>
+          <label>API Token</label><br/>
+          <input type="password" id="wca-token" style="width:100%" />
+        </div>
+        <div>
+          <label>Provider Name</label><br/>
+          <input type="text" id="wca-provider" style="width:100%" value="OpenCodeCloud" />
+        </div>
+      </form>`;
+    new Dialog({
+      title: 'WallCraft AI Settings',
+      content: html,
+      buttons: {
+        save: { label: 'Save', callback: (dlg) => {
+          const endpoint = dlg.find('#wca-endpoint').val();
+          const token = dlg.find('#wca-token').val();
+          const provider = dlg.find('#wca-provider').val();
+          // Persist via Foundry settings
+          game.settings.set('wallcraft-ai', 'endpointUrl', endpoint);
+          game.settings.set('wallcraft-ai', 'apiToken', token);
+          game.settings.set('wallcraft-ai', 'providerName', provider);
+        }}
+      },
+      default: 'save'
+    }).render(true);
+  }
+}
--- a/src/UIFlow.js
+++ b/src/UIFlow.js
@@ -0,0 +1,10 @@
+// Basic UI flow helpers for WallCraft AI (MVP)
+export function startAIPrepFlow() {
+  new Dialog({
+    title: 'WallCraft AI Prep (MVP)',
+    content: '<p>Trigger cloud AI to generate wall layout for the current scene. This is a placeholder MVP flow.</p>',
+    buttons: {
+      ok: { label: 'OK' }
+    }
+  }).render(true);
+}
--- a/structure.md
+++ b/structure.md
@@ -0,0 +1,18 @@
+WallCraft AI – Default File Structure
+
+- /modules/wallcraft-ai/
+  - module.json
+  - /src/
+    - AIPrep.js
+    - AIEndpoint.js
+    - PreviewLayer.js
+    - SettingsPanel.js
+    - UIFlow.js
+  - /agents.md
+  - /data-contracts.md
+  - /api-contract.md
+  - /onboarding.md
+  - /glossary.md
+  - /quick-start.md
+
+This structure keeps the core module logic separated from the documentation and keeps the docs versioned with the module code.