auvrynt 1.0.2 → 1.0.5

package/dist/workspaces.js

@@ -1,226 +1 @@
-import { randomUUID } from "node:crypto";
-import { mkdir, opendir, stat } from "node:fs/promises";
-import { dirname, join, relative, resolve, sep } from "node:path";
-import { loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
-import { createManagedWorktree } from "./git-worktrees.js";
-import { assertAllowedPath, isPathInsideRoot, resolveAllowedPath } from "./roots.js";
-import { loadWorkspaceSkills, markSkillActivated, resolveSkillReadPath, } from "./skills.js";
-export class WorkspaceRegistry {
-    config;
-    store;
-    workspaces = new Map();
-    constructor(config, store) {
-        this.config = config;
-        this.store = store;
-    }
-    async openWorkspace(input) {
-        const options = typeof input === "string" ? { path: input } : input;
-        const mode = options.mode ?? "checkout";
-        if (mode === "worktree") {
-            return this.openWorktreeWorkspace(options.path, options.baseRef);
-        }
-        return this.openCheckoutWorkspace(options.path);
-    }
-    getWorkspace(workspaceId) {
-        const workspace = this.workspaces.get(workspaceId);
-        if (workspace) {
-            this.store?.touchSession(workspaceId);
-            return workspace;
-        }
-        const session = this.store?.getSession(workspaceId);
-        if (!session) {
-            throw new Error(`Unknown workspaceId: ${workspaceId}. Call open_workspace first.`);
-        }
-        const root = this.assertWorkspaceRootAllowed(session.root, session.mode, session.sourceRoot);
-        const restoredWorkspace = {
-            id: session.id,
-            root,
-            mode: session.mode,
-            sourceRoot: session.sourceRoot,
-            worktree: session.mode === "worktree"
-                ? {
-                    path: root,
-                    baseRef: session.baseRef ?? "HEAD",
-                    baseSha: session.baseSha ?? "",
-                    dirtySource: false,
-                    detached: true,
-                    managed: session.managed,
-                }
-                : undefined,
-            ...this.loadSkillsForWorkspace(root),
-            activatedSkillDirs: new Set(),
-        };
-        this.store?.touchSession(workspaceId);
-        this.workspaces.set(restoredWorkspace.id, restoredWorkspace);
-        return restoredWorkspace;
-    }
-    resolvePath(workspace, inputPath) {
-        const absolutePath = resolveAllowedPath(inputPath, workspace.root, [workspace.root]);
-        if (!isPathInsideRoot(absolutePath, workspace.root)) {
-            throw new Error(`Path is outside workspace root: ${inputPath}`);
-        }
-        return absolutePath;
-    }
-    resolveReadPath(workspace, inputPath) {
-        try {
-            return {
-                absolutePath: this.resolvePath(workspace, inputPath),
-                readRoots: [workspace.root],
-            };
-        }
-        catch (workspaceError) {
-            const skillRead = resolveSkillReadPath(workspace.skills, workspace.activatedSkillDirs, inputPath);
-            if (!skillRead)
-                throw workspaceError;
-            return {
-                absolutePath: skillRead.absolutePath,
-                readRoots: [workspace.root, skillRead.skill.baseDir],
-                skillRead,
-            };
-        }
-    }
-    markReadPathLoaded(workspace, readPath) {
-        if (readPath.skillRead?.isSkillFile) {
-            markSkillActivated(workspace.activatedSkillDirs, readPath.skillRead.skill);
-        }
-    }
-    resolveWorkingDirectory(workspace, workingDirectory) {
-        const directory = workingDirectory ? this.resolvePath(workspace, workingDirectory) : workspace.root;
-        return assertAllowedPath(directory, [workspace.root]);
-    }
-    async openCheckoutWorkspace(path) {
-        const root = assertAllowedPath(path, this.config.allowedRoots);
-        await mkdir(root, { recursive: true });
-        const rootStats = await stat(root);
-        if (!rootStats.isDirectory()) {
-            throw new Error(`Workspace root must be a directory: ${path}`);
-        }
-        return this.createWorkspaceContext({ root, mode: "checkout" });
-    }
-    async openWorktreeWorkspace(path, baseRef) {
-        const worktree = await createManagedWorktree({
-            sourcePath: path,
-            baseRef,
-            config: this.config,
-        });
-        return this.createWorkspaceContext({
-            root: worktree.path,
-            mode: "worktree",
-            sourceRoot: worktree.sourceRoot,
-            worktree,
-        });
-    }
-    async createWorkspaceContext(input) {
-        const workspace = {
-            id: `ws_${randomUUID()}`,
-            root: input.root,
-            mode: input.mode,
-            sourceRoot: input.sourceRoot,
-            worktree: input.worktree,
-            ...this.loadSkillsForWorkspace(input.root),
-            activatedSkillDirs: new Set(),
-        };
-        this.store?.createSession({
-            id: workspace.id,
-            root: workspace.root,
-            mode: workspace.mode,
-            sourceRoot: workspace.sourceRoot,
-            baseRef: workspace.worktree?.baseRef,
-            baseSha: workspace.worktree?.baseSha,
-            managed: workspace.worktree?.managed,
-        });
-        this.workspaces.set(workspace.id, workspace);
-        const agentsFiles = this.loadInitialAgentsFiles(workspace.root);
-        const availableAgentsFiles = await this.findAvailableAgentsFiles(workspace.root, agentsFiles);
-        return { workspace, agentsFiles, availableAgentsFiles };
-    }
-    loadSkillsForWorkspace(root) {
-        const result = loadWorkspaceSkills(this.config, root);
-        return {
-            skills: result.skills,
-            skillDiagnostics: result.diagnostics,
-        };
-    }
-    assertWorkspaceRootAllowed(root, mode, sourceRoot) {
-        if (mode === "worktree") {
-            if (!sourceRoot) {
-                throw new Error(`Stored worktree workspace is missing sourceRoot: ${root}`);
-            }
-            assertAllowedPath(sourceRoot, this.config.allowedRoots);
-            return assertAllowedPath(root, [this.config.worktreeRoot]);
-        }
-        return assertAllowedPath(root, this.config.allowedRoots);
-    }
-    loadInitialAgentsFiles(root) {
-        const agentDir = resolve(this.config.agentDir);
-        return loadProjectContextFiles({ cwd: root, agentDir })
-            .filter((file) => {
-            const path = resolve(file.path);
-            if (isPathInsideRoot(path, agentDir))
-                return true;
-            return isPathInsideRoot(path, root) && dirname(path) === root;
-        })
-            .map((file) => ({
-            path: resolve(file.path),
-            content: file.content,
-        }));
-    }
-    async findAvailableAgentsFiles(root, loadedFiles) {
-        const loadedPaths = new Set(loadedFiles.map((file) => resolve(file.path)));
-        const discovered = [];
-        await walkWorkspace(root, async (path, entry) => {
-            if (!entry.isFile())
-                return;
-            if (!CONTEXT_FILE_NAMES.has(entry.name))
-                return;
-            if (loadedPaths.has(path))
-                return;
-            discovered.push({ path });
-        });
-        return discovered.sort((a, b) => a.path.localeCompare(b.path));
-    }
-}
-const CONTEXT_FILE_NAMES = new Set(["AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"]);
-const SKIPPED_CONTEXT_DIRS = new Set([
-    ".git",
-    ".hg",
-    ".svn",
-    ".auvrynt",
-    "node_modules",
-    "dist",
-    "build",
-    ".next",
-    ".turbo",
-    ".cache",
-]);
-export function formatAgentsPath(path, workspaceRoot) {
-    if (!workspaceRoot)
-        return path.split(sep).join("/");
-    const relationship = relative(workspaceRoot, path);
-    if (relationship === "" ||
-        relationship.startsWith("..") ||
-        relationship === ".." ||
-        relationship.includes(`..${sep}`)) {
-        return path.split(sep).join("/");
-    }
-    return relationship.split(sep).join("/");
-}
-async function walkWorkspace(directory, visit) {
-    let entries;
-    try {
-        entries = await opendir(directory);
-    }
-    catch {
-        return;
-    }
-    for await (const entry of entries) {
-        const path = join(directory, entry.name);
-        if (entry.isDirectory()) {
-            if (!SKIPPED_CONTEXT_DIRS.has(entry.name)) {
-                await walkWorkspace(path, visit);
-            }
-            continue;
-        }
-        await visit(path, entry);
-    }
-}
+export * from "./workspace/workspaces.js";

package/docs/CREATOR_STORE_FREE_ASSETS.md

@@ -0,0 +1,162 @@
+# Free Creator Store Assets — Sample Catalog + Guide
+
+**Generated:** 2026-08-10  
+**Scope:** Free (`priceFilter=free`) Creator Store **Models** only  
+**Limit:** MCP returns max ~20 results per query. The Store has millions of assets — this is a **starter sample**, not a full dump.
+
+---
+
+## How to use this guide
+
+### When to use Creator Store free models
+| Need | Use store models when… | Prefer custom / Luau when… |
+|------|------------------------|----------------------------|
+| **Environment** | Trees, rocks, skyboxes, roads for quick map fill | You need exact style, low part count, or streaming budget |
+| **Buildings** | Blockouts, RP houses, horror maps | Unique architecture, collision precision |
+| **Vehicles** | Prototype driving / spawners | Real vehicle physics you control |
+| **Weapons / gear** | Placeholders, classic tools | Secure combat (validate damage on server) |
+| **Furniture** | Interior fill for RP / café | Optimized low-poly sets you own |
+| **Systems (admin, leaderboards)** | Speed-running features | You must own/audit every script |
+
+### Safety rules (always)
+1. **Inspect scripts** before publishing — free models often ship backdoors, admin abuse, or remote spam.
+2. Prefer assets from **Roblox** or known creators; strip unknown `Script`/`LocalScript` if unsure.
+3. **Paid assets** cannot be inserted until purchased — this list is free only.
+4. Some free assets still **fail to insert** (moderation / package restrictions) — try the next ID.
+5. Insert via MCP: `insert_asset` with `assetId`, `assetType: "Model"`, `assetName`.
+
+### MCP search recipe
+```
+search_asset:
+  scope: creator_store
+  priceFilter: free
+  assetType: Model   # or Audio, Mesh, Image, Decal, Package…
+  query: "tree forest"
+  maxResults: 20
+```
+
+---
+
+## Starter / utilities
+
+| Name | Asset ID | Creator | When to use | URL |
+|------|----------|---------|-------------|-----|
+| Spawn Point | 10498769556 | agentphilip07 | Default player spawn marker | [link](https://create.roblox.com/store/asset/10498769556) |
+| Invisible Spawn Point | 9762951603 | SyncSnacks | Hidden spawn | [link](https://create.roblox.com/store/asset/9762951603) |
+| spawn point | 13944666959 | its_fladi | Alternate spawn visual | [link](https://create.roblox.com/store/asset/13944666959) |
+| Grass Baseplate | 10100805 | Roblox | Classic grass floor | [link](https://create.roblox.com/store/asset/10100805) |
+| Grass Baseplate | 2286648632 | colorfuleagle1001 | Fits default baseplate size | [link](https://create.roblox.com/store/asset/2286648632) |
+| Old stud block | 11257095071 | cnnendot4133 | Retro stud props | [link](https://create.roblox.com/store/asset/11257095071) |
+| Sword | 47433 | Roblox | Classic linked sword tool | [link](https://create.roblox.com/store/asset/47433) |
+| Noob NPC | 4446576906 | Vertixer1337 | Placeholder NPC | [link](https://create.roblox.com/store/asset/4446576906) |
+| Shift to run | 8459456709 | ScriptedMikeey | Sprint script prototype — **audit scripts** | [link](https://create.roblox.com/store/asset/8459456709) |
+| HD Admin | 857927023 | ForeverHD | Admin commands — **production risk; audit heavily** | [link](https://create.roblox.com/store/asset/857927023) |
+| Time Played Leaderboard | 5352156968 | RenanMSV | Playtime board — **DataStore costs** | [link](https://create.roblox.com/store/asset/5352156968) |
+
+---
+
+## Sky / atmosphere
+
+| Name | Asset ID | When to use |
+|------|----------|-------------|
+| Realistic Sky | 4607457995 | Generic day skybox starter |
+| Aesthetic sky | 7108851308 | Mood / vibe maps |
+| Classic Roblox Sky (SKYBOX) | 339406852 | Nostalgia / classic places |
+| CakeUp Night Sky Galaxy Planets | 15983996673 | Night / space vibe |
+
+---
+
+## Nature / forest
+
+| Name | Asset ID | When to use |
+|------|----------|-------------|
+| Stud Tree Classic Retro | 83155033985612 | Classic/stud aesthetic maps |
+| Realistic Log Wood | 136869545721659 | Forest floor props |
+| PBR Nature Pack Wild Trees | 123405066104552 | Higher-detail foliage packs |
+| Forest Tower / Tree House | 72105624698726 | Adventure / hideout |
+| Realistic Pine Tree | 90843648266001 | Evergreen biome |
+| Winter Forest Pack | 106336474170677 | Snow maps |
+| Autumn Sky Fall Tree | 139035690932109 | Fall biome |
+| Cartoon Forest Lowpoly Pack | 127971452858364 | Stylized / mobile-friendly |
+| Realistic Moving Tree | 105750520391033 | Animated canopy (perf cost) |
+| PBR Realistic Tree Pack | 106624131560617 | Dense forest fill |
+
+---
+
+## Buildings / houses
+
+| Name | Asset ID | When to use |
+|------|----------|-------------|
+| Classic House | 8959904556 | Simple suburban starter |
+| Horror Game House Building | 16703737576 | Horror blockout |
+| Horror Game House Building | 18574951722 | Variant horror house |
+| Modern Apartment Building | 18888365209 | City RP |
+| Small House Brookhaven-style | 77692490790411 | City RP homes |
+| Apartment building Urban Loft | 114126832502867 | Dense urban |
+| Modern Town City Building | 93988667845755 | Street / town strip |
+| Brookhaven Villa 1 | 124487663909260 | Luxury RP house |
+| Destroyed Building | 120370036715023 | Apocalypse maps |
+| Buildings Walls Houses pack | 129441595821867 | Modular town pieces |
+
+---
+
+## Roads / vehicles
+
+| Name | Asset ID | When to use |
+|------|----------|-------------|
+| Road | 14102233829 | Quick road strip |
+| 2019 Sports Car | 6810376207 | Showcase car |
+| Army jeep / military | 77018157368877 | War / mil RP |
+| Classic Pickup Truck | 92651703326783 | Civilian traffic |
+| Classic Roblox Jeep Spawner | 114110323866454 | Classic vehicle spawn |
+| Free Humvee | 125960240887706 | Military transport |
+| Abandoned Car | 97780315774758 | Wasteland prop |
+| Parking Space | 71334976821290 | Parking lot detail |
+
+---
+
+## Weapons / combat (placeholders only)
+
+| Name | Asset ID | When to use |
+|------|----------|-------------|
+| Low Poly Weapon Pack | 102927883946599 | Style mockups |
+| Classic Weapons Rifle… | 105727800460617 | Classic FPS look |
+| Classic Roblox Weapon Pack | 105002355098155 | Retro gear |
+| FPS Weapon System Pack | 87452459242470 | Prototype only — **rewrite combat server-side** |
+
+---
+
+## Furniture / interiors
+
+| Name | Asset ID | When to use |
+|------|----------|-------------|
+| Cafe Table Chair | 132188174151502 | Café / hangout |
+| Table Chairs Dining Set | 81429788184908 | Dining rooms |
+| Dining Table Chairs Kitchen | 106869233942930 | House interiors |
+| Classic 2007 Furniture | 110463242735527 | Retro interiors |
+| Furniture Couch Tables Office | 130155490858637 | Office / lobby |
+
+---
+
+## When *not* to use free models
+
+- **Core game loop** (currency, inventory, combat resolution) — write your own server code.
+- **Monetization / admin** — free admin kits are high abuse risk.
+- **Final art pass** — many free models are high part-count or poorly optimized.
+- **Anything you cannot open and understand** in Explorer.
+
+---
+
+## Refreshing this list
+
+Re-run searches with different `query` / `assetType` values. Store rankings change often.  
+For Audio/Mesh/Decal, set `assetType` accordingly (inventory APIs often require one type per call).
+
+**Insert example (MCP):**
+```
+insert_asset:
+  assetId: "47433"
+  assetType: Model
+  assetName: Sword
+  parentPath: game.Workspace
+```

package/docs/DEVELOPMENT_TOOLS.md

@@ -1,100 +1,143 @@
-# Auvrynt Local Development Tools Guide
-
-Auvrynt extends Model Context Protocol (MCP) with tools for web application development, C#/.NET software development, Godot 4 game development, image inspection/comparison, and persistent process management.
-
----
-
-## Architecture & Security Boundaries
-
+# Auvrynt Local Development Tools Guide
+
+Auvrynt extends Model Context Protocol (MCP) with tools for web application development, C#/.NET software development, Godot 4 game development, Aseprite pixel-art editing, image inspection/comparison, and persistent process management.
+
+---
+
+## Architecture & Security Boundaries
+
 Use `get_connection_status` after `open_workspace` to automatically probe the
-authenticated MCP session, Blender, Godot, Cloudflare Tunnel, Serena, browser
+authenticated MCP session, Blender, Aseprite, Godot, Cloudflare Tunnel, Serena, browser
 support, Chrome MCP registration, and tracked workspace processes. Blender
-detection includes the Blender Lab MCP endpoint shown in Blender preferences
-(`localhost:9876` by default) and the Auvrynt bridge (`127.0.0.1:49323`).
+scene tools connect directly to the Blender Lab MCP endpoint shown in Blender
+preferences (`localhost:9876` by default).
 Godot detection distinguishes a running Godot process from a reachable Auvrynt
 editor bridge (`127.0.0.1:49322`). Cloudflare Tunnel and Serena report whether
 their executables are installed and whether their processes are running. A
 browser marked `available` means Playwright is installed; browser sessions are
 created on demand and are not persistent connections.
-
-1. **Workspace Boundary Enforcement**: Every path input must be relative to the opened workspace root. Path traversal (`..`) or symbolic links escaping the workspace are blocked by `WorkspaceRegistry.resolvePath`.
-2. **Persistent Processes**: Long-running servers, .NET applications, and Godot games run as background child processes managed by `ProcessManager`. Standard output and error streams are captured in bounded in-memory log buffers (max 1000 lines).
-3. **Secret Redaction**: Environment variables containing keywords like `TOKEN`, `SECRET`, `PASSWORD`, `KEY`, or `CONNECTION_STRING` are automatically redacted in responses and log entries.
-4. **Browser & Network Security**: `capture_page_screenshot` and `inspect_page` enforce strict SSRF defenses, blocking non-HTTP(S) schemes (`file:`, `data:`, `javascript:`) and cloud metadata / private network IP addresses unless targeting recognized local development hosts (`localhost`, `127.0.0.1`, `[::1]`).
-
----
-
-## Tool Reference
-
-### Phase 1: Persistent Process Management
-- `start_process`: Spawns background process inside workspace. Returns `processId`.
-- `get_process_logs`: Tail stdout/stderr for a process (default 100 lines, max 500 lines).
-- `list_processes`: List tracked background processes for a workspace.
-- `stop_process`: Gracefully stop or force-kill (`force: true`) process tree.
-
-### Phase 2: Structured Project Discovery & Search
-- `glob_files`: Fast file globbing respecting `.gitignore` and default exclusions (`.git`, `node_modules`, `dist`, `bin`, `obj`).
-- `search_text`: Workspace-wide text search returning matching lines and context snippets.
-- `inspect_project`: Auto-detect Node.js, TypeScript, .NET, Godot, Python, Git projects and recommended build/run/test commands.
-
-### Phase 3: Web-Development Tools
-- `start_dev_server`: Launch web dev server (auto-detects `npm run dev` script).
-- `capture_page_screenshot`: Playwright browser screenshot saved inside workspace and returned as MCP image content.
-- `inspect_page`: Extract structured page title, headings, buttons, links, landmarks, console errors, and failed requests.
-
-### Phase 4: Image and Screenshot Inspection
-- `inspect_image`: Inspect dimensions, format, MIME type, alpha, and color palette.
-- `compare_images`: RGBA pixel-by-pixel image comparison returning match %, changed pixels, and optional diff PNG output.
-- `inspect_sprite`: Analyze sprite sheet grid dimensions, cell divisibility, and frame bounds.
-- `split_sprite_sheet`: Slices sprite sheet into individual frame PNGs saved inside the workspace.
-
-### Phase 5: C# and .NET Tools
-- `inspect_dotnet_project`: Parse `.csproj`, `.fsproj`, `.sln` for SDK style, frameworks, packages, and test runner.
-- `dotnet_restore`: Run `dotnet restore` securely.
-- `dotnet_build`: Run `dotnet build` returning structured compiler errors/warnings with line and column.
-- `dotnet_test`: Run `dotnet test` returning pass/fail/skip counts, failed test names, and assertion messages.
-- `dotnet_run`: Launch .NET app as persistent process.
-- `dotnet_format`: Run `dotnet format` (`verifyOnly` mode supported).
-
-### Phase 6: Godot 4 Tools
-- `detect_godot_project`: Read `project.godot` for project name, main scene, renderer, autoloads, input actions.
-- `godot_run`: Launch Godot game or editor as persistent process. Environment variable `GODOT_EXECUTABLE` overrides path.
-- `inspect_godot_scene`: Parse `.tscn` text scene trees, node types, signals, and external resources.
-
-### Phase 7: Window Capture
-- `capture_window`: Capture screenshot of Auvrynt-tracked application window (Windows only).
-- `godot_capture_game`: Wrap window capture for Godot game processes.
-
----
-
-## Development Workflows
-
-### Web Development Workflow
-```text
-1. open_workspace(path)
-2. inspect_project(workspaceId)
-3. start_dev_server(workspaceId)
-4. capture_page_screenshot(workspaceId, url="http://localhost:3000", outputPath="screenshots/home.png")
-5. inspect_page(workspaceId, url="http://localhost:3000")
-6. stop_process(workspaceId, processId)
-```
-
-### .NET Workflow
-```text
-1. open_workspace(path)
-2. inspect_dotnet_project(workspaceId, projectPath="MyApp.csproj")
-3. dotnet_restore(workspaceId, projectPath="MyApp.csproj")
-4. dotnet_build(workspaceId, projectPath="MyApp.csproj")
-5. dotnet_test(workspaceId, projectPath="MyApp.Tests.csproj")
-6. dotnet_run(workspaceId, projectPath="MyApp.csproj")
-```
-
-### Godot 4 Workflow
-```text
-1. open_workspace(path)
-2. detect_godot_project(workspaceId)
-3. inspect_godot_scene(workspaceId, scenePath="scenes/main.tscn")
-4. godot_run(workspaceId, projectPath=".")
-5. godot_capture_game(workspaceId, processId, outputPath="captures/game.png")
-6. stop_process(workspaceId, processId)
-```
+
+1. **Workspace Boundary Enforcement**: Every path input must be relative to the opened workspace root. Path traversal (`..`) or symbolic links escaping the workspace are blocked by `WorkspaceRegistry.resolvePath`.
+2. **Persistent Processes**: Long-running servers, .NET applications, and Godot games run as background child processes managed by `ProcessManager`. Standard output and error streams are captured in bounded in-memory log buffers (max 1000 lines).
+3. **Secret Redaction**: Environment variables containing keywords like `TOKEN`, `SECRET`, `PASSWORD`, `KEY`, or `CONNECTION_STRING` are automatically redacted in responses and log entries.
+4. **Browser & Network Security**: `capture_page_screenshot` and `inspect_page` enforce strict SSRF defenses, blocking non-HTTP(S) schemes (`file:`, `data:`, `javascript:`) and cloud metadata / private network IP addresses unless targeting recognized local development hosts (`localhost`, `127.0.0.1`, `[::1]`).
+
+---
+
+## Tool Reference
+
+### Phase 1: Persistent Process Management
+- `start_process`: Spawns background process inside workspace. Returns `processId`.
+- `get_process_logs`: Tail stdout/stderr for a process (default 100 lines, max 500 lines).
+- `list_processes`: List tracked background processes for a workspace.
+- `stop_process`: Gracefully stop or force-kill (`force: true`) process tree.
+
+### Phase 2: Structured Project Discovery & Search
+- `glob_files`: Fast file globbing respecting `.gitignore` and default exclusions (`.git`, `node_modules`, `dist`, `bin`, `obj`).
+- `search_text`: Workspace-wide text search returning matching lines and context snippets.
+- `inspect_project`: Auto-detect Node.js, TypeScript, .NET, Godot, Python, Git projects and recommended build/run/test commands.
+
+### Phase 3: Web-Development Tools
+- `start_dev_server`: Launch web dev server (auto-detects `npm run dev` script).
+- `capture_page_screenshot`: Playwright browser screenshot saved inside workspace and returned as MCP image content.
+- `inspect_page`: Extract structured page title, headings, buttons, links, landmarks, console errors, and failed requests.
+
+### Phase 3b: Agent Reach (external internet platforms)
+Requires the **web / Playwright** integration profile (`auvrynt start web`). Wraps the open-source [Agent Reach](https://github.com/Panniantong/Agent-Reach) CLI for free platform read/search (Twitter/X, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu, RSS, web search, and more).
+
+- `agent_reach_status`: Detect whether `agent-reach` is on PATH (and version when available).
+- `agent_reach_doctor`: Run `agent-reach doctor` / `doctor --json` for channel health.
+- `agent_reach_guide`: Install/update URLs and platform notes without executing the CLI.
+
+Agent Reach is an installer + health-checker + router. After setup, agents call upstream tools (`yt-dlp`, `gh`, `twitter`, `opencli`, …) directly. Cookies remain on the local machine.
+
+### Phase 4: Image and Screenshot Inspection
+- `inspect_image`: Inspect dimensions, format, MIME type, alpha, and color palette.
+- `compare_images`: RGBA pixel-by-pixel image comparison returning match %, changed pixels, and optional diff PNG output.
+- `inspect_sprite`: Analyze sprite sheet grid dimensions, cell divisibility, and frame bounds.
+- `split_sprite_sheet`: Slices sprite sheet into individual frame PNGs saved inside the workspace.
+
+### Phase 5: C# and .NET Tools
+- `inspect_dotnet_project`: Parse `.csproj`, `.fsproj`, `.sln` for SDK style, frameworks, packages, and test runner.
+- `dotnet_restore`: Run `dotnet restore` securely.
+- `dotnet_build`: Run `dotnet build` returning structured compiler errors/warnings with line and column.
+- `dotnet_test`: Run `dotnet test` returning pass/fail/skip counts, failed test names, and assertion messages.
+- `dotnet_run`: Launch .NET app as persistent process.
+- `dotnet_format`: Run `dotnet format` (`verifyOnly` mode supported).
+
+### Phase 6: Godot 4 Tools
+- `detect_godot_project`: Read `project.godot` for project name, main scene, renderer, autoloads, input actions.
+- `godot_run`: Launch Godot game or editor as persistent process. Environment variable `GODOT_EXECUTABLE` overrides path.
+- `inspect_godot_scene`: Parse `.tscn` text scene trees, node types, signals, and external resources.
+
+### Phase 7: Aseprite Pixel-Art Tools
+Auvrynt exposes 36 grouped Aseprite tools. Core categories:
+- Detection/readback/live editor: `aseprite_detect`, `aseprite_live_editor`, `aseprite_capture_current`, `aseprite_capture_canvas`, `aseprite_inspect_file`, `aseprite_read_pixels`.
+  - The live editor tool includes 46 allowlisted bridge commands for unsaved drawing, selections, layers/cels/tags, palettes, transforms, frame operations, cross-document copying, and live analysis.
+- QA: `aseprite_audit_sprite`, `aseprite_compare_documents`, `aseprite_animation_audit`.
+- Safety/maintenance: `aseprite_file_safety`, `aseprite_maintenance`, `aseprite_batch_process`, `aseprite_recovery`, `aseprite_extensions`.
+- Drawing/regions: `aseprite_create_sprite`, `aseprite_set_pixels`, `aseprite_draw_shapes`, `aseprite_draw_stroke`, `aseprite_draw_advanced`, `aseprite_edit_region`, `aseprite_manage_mask`, `aseprite_run_safe_command`.
+- Structure/animation: `aseprite_manage_layers`, `aseprite_compose_layers`, `aseprite_manage_frames`, `aseprite_manage_animation`, `aseprite_manage_tags`, `aseprite_manage_cels`, `aseprite_manage_document`.
+- Color/tilemap/import/export: `aseprite_set_palette`, `aseprite_manage_color`, `aseprite_import_sprite_sheet`, `aseprite_manage_tilemap`, `aseprite_export_sprite_sheet`, `aseprite_manage_export_preset`, `aseprite_convert_file`.
+
+Destructive source edits accept `expectedVersion` and `checkpoint`. Use the SHA-256 returned by `aseprite_file_safety` to reject stale writes. Recovery deletion and extension mutation additionally require `allowGlobalWrite=true`.
+
+### Phase 8: Window Capture
+- `capture_window`: Capture screenshot of Auvrynt-tracked application window (Windows only).
+- `godot_capture_game`: Wrap window capture for Godot game processes.
+
+---
+
+## Development Workflows
+
+### Web Development Workflow
+```text
+1. open_workspace(path)
+2. inspect_project(workspaceId)
+3. start_dev_server(workspaceId)
+4. capture_page_screenshot(workspaceId, url="http://localhost:3000", outputPath="screenshots/home.png")
+5. inspect_page(workspaceId, url="http://localhost:3000")
+6. stop_process(workspaceId, processId)
+```
+
+### External platform research (Agent Reach)
+```text
+1. Enable web profile: auvrynt start web
+2. agent_reach_status
+3. If missing → agent_reach_guide → user installs from GitHub install.md
+4. agent_reach_doctor (json optional)
+5. Use upstream CLIs via bash for the specific platform task
+```
+
+### .NET Workflow
+```text
+1. open_workspace(path)
+2. inspect_dotnet_project(workspaceId, projectPath="MyApp.csproj")
+3. dotnet_restore(workspaceId, projectPath="MyApp.csproj")
+4. dotnet_build(workspaceId, projectPath="MyApp.csproj")
+5. dotnet_test(workspaceId, projectPath="MyApp.Tests.csproj")
+6. dotnet_run(workspaceId, projectPath="MyApp.csproj")
+```
+
+### Aseprite Workflow
+```text
+1. open_workspace(path)
+2. aseprite_detect(workspaceId)
+3. aseprite_inspect_file(workspaceId, filePath="sprites/hero.aseprite")
+4. aseprite_read_pixels(...) or aseprite_audit_sprite(...) for exact evidence
+5. aseprite_file_safety(action="status") -> retain version
+6. aseprite_set_pixels(..., expectedVersion=version, checkpoint=true)
+7. aseprite_compare_documents(...) or aseprite_animation_audit(...)
+8. aseprite_manage_export_preset(action="run", name="game")
+9. aseprite_manage_export_preset(action="validate", name="game")
+```
+
+### Godot 4 Workflow
+```text
+1. open_workspace(path)
+2. detect_godot_project(workspaceId)
+3. inspect_godot_scene(workspaceId, scenePath="scenes/main.tscn")
+4. godot_run(workspaceId, projectPath=".")
+5. godot_capture_game(workspaceId, processId, outputPath="captures/game.png")
+6. stop_process(workspaceId, processId)
+```

package/docs/assets/auvrynt-icon.svg

@@ -0,0 +1,20 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" role="img" aria-labelledby="title desc">
+  <title id="title">Auvrynt icon</title>
+  <desc id="desc">Minimal purple A monogram with a sweeping cross stroke on a dark purple rounded square.</desc>
+  <defs>
+    <linearGradient id="bg" x1="28" y1="20" x2="220" y2="236" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#160625"/>
+      <stop offset="0.55" stop-color="#250a3d"/>
+      <stop offset="1" stop-color="#12051f"/>
+    </linearGradient>
+    <linearGradient id="mark" x1="70" y1="204" x2="188" y2="52" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#8b5cf6"/>
+      <stop offset="0.52" stop-color="#a855f7"/>
+      <stop offset="1" stop-color="#c084fc"/>
+    </linearGradient>
+  </defs>
+  <rect x="8" y="8" width="240" height="240" rx="52" fill="url(#bg)"/>
+  <path d="M60 199 112 93c6-13 10-23 16-23 7 0 11 10 17 23l35 72-28 2-24-52-26 55-42 29Z" fill="url(#mark)"/>
+  <path d="M58 201c39-42 88-72 151-76-53 8-100 29-145 65l-6 11Z" fill="url(#mark)"/>
+  <path d="m158 145 19 39c2 4 5 6 9 6h13l-23-48-18 3Z" fill="#7c3aed"/>
+</svg>