Merge pull request #16 from DavidUmKongs/chore/sync-upstream-2026-03-24

Sync upstream main into codex and verify rebaseability

Author: DavidUmKongs

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,7 +1,7 @@
 name: "Bug report"
 description: "Report a bug to help us improve Pixel Agents."
 title: "[Bug]: "
-labels: ["bug"]
+labels: ["type: bug"]
 body:
   - type: textarea
     id: description

.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +1,5 @@
 blank_issues_enabled: false
 contact_links:
-  - name: "Feature request"
-    url: "https://github.com/pablodelucca/pixel-agents/discussions/categories/ideas"
-    about: "Suggest new features or ideas in Discussions."
-  - name: "Question"
+  - name: "Question / Help"
     url: "https://github.com/pablodelucca/pixel-agents/discussions/categories/q-a"
     about: "Ask questions and get help in Discussions."

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,53 @@
+name: "Feature request"
+description: "Suggest a new feature, idea, or improvement for Pixel Agents."
+title: "[Feature]: "
+labels: ["type: feature"]
+body:
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: "Pre-flight checklist"
+      options:
+        - label: "I have searched existing issues and this is not a duplicate"
+          required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: "Problem or motivation"
+      description: "What problem does this solve, or what need does it address? A clear problem statement helps us prioritize."
+      placeholder: "e.g., When I have many agents open, I can't tell which terminal each character is connected to."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: "Proposed solution"
+      description: "How should it work? Describe the behavior, UI, or API you envision."
+      placeholder: "e.g., Show the terminal name as a label above each character, toggled via a setting."
+    validations:
+      required: true
+
+  - type: dropdown
+    id: importance
+    attributes:
+      label: "How important is this to you?"
+      options:
+        - "Nice to have"
+        - "Would improve my workflow"
+        - "Critical — blocking my use case"
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: "Alternatives considered"
+      description: "Have you considered other solutions or workarounds?"
+
+  - type: textarea
+    id: context
+    attributes:
+      label: "Additional context"
+      description: "Screenshots, mockups, links to related issues or discussions."

.github/workflows/pr-title.yml

@@ -0,0 +1,31 @@
+name: PR Title
+
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            refactor
+            chore
+            docs
+            style
+            perf
+            test
+            ci
+            build
+          requireScope: false
+          subjectPattern: ^[a-z].+$
+          subjectPatternError: "PR title subject must start with a lowercase letter: '{subject}'"

.github/workflows/update-badges.yml

@@ -2,7 +2,7 @@ name: Update Badge Stats
 
 on:
   schedule:
-    - cron: '0 6 * * *'
+    - cron: '0 6,14,22 * * *'
   workflow_dispatch:
 
 jobs:

.gitignore

@@ -29,3 +29,13 @@ Thumbs.db
 .claude/
 /sprites-export
 .omx/
+
+
+# Local notes (not for commit)
+/notes/
+
+# Auto-generated PR review metadata
+comments.json
+pr_comments.json
+pr_reviews.json
+reviews.json

CLAUDE.md

@@ -11,6 +11,7 @@ src/                          — Extension backend (Node.js, VS Code API)
   PixelAgentsViewProvider.ts   — WebviewViewProvider, message dispatch, asset loading
   assetLoader.ts              — PNG parsing, sprite conversion, catalog building, default layout loading
   agentManager.ts             — Terminal lifecycle: launch, remove, restore, persist
+  configPersistence.ts        — User-level config file I/O (~/.pixel-agents/config.json), external asset directories
   layoutPersistence.ts        — User-level layout file I/O (~/.pixel-agents/layout.json), migration, cross-window watching
   fileWatcher.ts              — fs.watch + polling, readNewLines, /clear detection, terminal adoption
   transcriptParser.ts         — JSONL parsing: tool_use/tool_result → webview messages
@@ -73,7 +74,7 @@ scripts/                      — 7-stage asset extraction pipeline
 
 **Vocabulary**: Terminal = VS Code terminal running the selected agent CLI. Session = JSONL conversation file. Agent = webview character bound 1:1 to a terminal.
 
-**Extension ↔ Webview**: `postMessage` protocol. Key messages: `openAgent`, `agentCreated/Closed`, `focusAgent`, `agentToolStart/Done/Clear`, `agentStatus`, `existingAgents`, `layoutLoaded`, `furnitureAssetsLoaded`, `floorTilesLoaded`, `wallTilesLoaded`, `saveLayout`, `saveAgentSeats`, `exportLayout`, `importLayout`, `settingsLoaded`, `setSoundEnabled`.
+**Extension ↔ Webview**: `postMessage` protocol. Key messages: `openAgent`, `agentCreated/Closed`, `focusAgent`, `agentToolStart/Done/Clear`, `agentStatus`, `existingAgents`, `layoutLoaded`, `furnitureAssetsLoaded`, `floorTilesLoaded`, `wallTilesLoaded`, `saveLayout`, `saveAgentSeats`, `exportLayout`, `importLayout`, `settingsLoaded` (includes `externalAssetDirectories`), `setSoundEnabled`, `addExternalAssetDirectory`, `removeExternalAssetDirectory` (field: `path`), `externalAssetDirectoriesUpdated` (field: `dirs`).
 
 **One-agent-per-terminal**: Each "+ Agent" click launches the configured backend (`codex` or `claude`) and immediately creates a bound agent. Backends with deterministic session files can poll for the expected JSONL; others rely on project scanning/adoption.
 
@@ -89,7 +90,7 @@ JSONL transcripts are adapter-specific: Claude uses `~/.claude/projects/<project
 
 **Extension state per agent**: `id, terminalRef, projectDir, jsonlFile, fileOffset, lineBuffer, activeToolIds, activeToolStatuses, activeSubagentToolNames, isWaiting`.
 
-**Persistence**: Agents persisted to `workspaceState` key `'pixel-agents.agents'` (includes palette/hueShift/seatId). **Layout persisted to `~/.pixel-agents/layout.json`** (user-level, shared across all VS Code windows/workspaces). `layoutPersistence.ts` handles all file I/O: `readLayoutFromFile()`, `writeLayoutToFile()` (atomic via `.tmp` + rename), `migrateAndLoadLayout()` (checks file → migrates old workspace state → falls back to bundled default), `watchLayoutFile()` (hybrid `fs.watch` + 2s polling for cross-window sync). On save, `markOwnWrite()` prevents the watcher from re-reading our own write. External changes push `layoutLoaded` to the webview; skipped if the editor has unsaved changes (last-save-wins). On webview ready: `restoreAgents()` matches persisted entries to live terminals. `nextAgentId`/`nextTerminalIndex` advanced past restored values. **Default layout**: When no saved layout file exists and no workspace state to migrate, a bundled `default-layout.json` is loaded from `assets/` and written to the file. If that also doesn't exist, `createDefaultLayout()` generates a basic office. To update the default: run "Pixel Agents: Export Layout as Default" from the command palette (writes current layout to `webview-ui/public/assets/default-layout.json`), then rebuild. **Export/Import**: Settings modal offers Export Layout (save dialog → JSON file) and Import Layout (open dialog → validates `version: 1` + `tiles` array → writes to layout file + pushes `layoutLoaded` to webview).
+**Persistence**: Agents persisted to `workspaceState` key `'pixel-agents.agents'` (includes palette/hueShift/seatId). **Layout persisted to `~/.pixel-agents/layout.json`** (user-level, shared across all VS Code windows/workspaces). `layoutPersistence.ts` handles all file I/O: `readLayoutFromFile()`, `writeLayoutToFile()` (atomic via `.tmp` + rename), `migrateAndLoadLayout()` (checks file → migrates old workspace state → falls back to bundled default), `watchLayoutFile()` (hybrid `fs.watch` + 2s polling for cross-window sync). On save, `markOwnWrite()` prevents the watcher from re-reading our own write. External changes push `layoutLoaded` to the webview; skipped if the editor has unsaved changes (last-save-wins). On webview ready: `restoreAgents()` matches persisted entries to live terminals. `nextAgentId`/`nextTerminalIndex` advanced past restored values. **Default layout**: When no saved layout file exists and no workspace state to migrate, a bundled `default-layout.json` is loaded from `assets/` and written to the file. If that also doesn't exist, `createDefaultLayout()` generates a basic office. To update the default: run "Pixel Agents: Export Layout as Default" from the command palette (writes current layout to `webview-ui/public/assets/default-layout.json`), then rebuild. **Export/Import**: Settings modal offers Export Layout (save dialog → JSON file) and Import Layout (open dialog → validates `version: 1` + `tiles` array → writes to layout file + pushes `layoutLoaded` to webview). **Config persisted to `~/.pixel-agents/config.json`** (user-level, shared across windows). `configPersistence.ts` handles read/write with atomic tmp+rename. Currently stores `externalAssetDirectories: string[]` for external asset pack paths. **External asset directories**: Settings modal offers Add/Remove Asset Directory. External furniture merged with bundled assets on boot and on add/remove via `mergeLoadedAssets()` (external IDs override bundled on collision).
 
 ## Office UI
 

CONTRIBUTING.md

@@ -14,8 +14,8 @@ This project is licensed under the [MIT License](LICENSE), so your contributions
 ### Setup
 
 ```bash
-git clone https://github.com/pablodelucca/pixel-agents.git
-cd pixel-agents
+git clone https://github.com/DavidUmKongs/oh-my-pixel-agents.git
+cd oh-my-pixel-agents
 npm install
 cd webview-ui && npm install && cd ..
 npm run build
@@ -106,17 +106,20 @@ These rules are set to `warn` — they won't block your PR but will flag violati
    ```
    CI runs these same checks automatically on every PR.
 4. Open a pull request against `main` with:
+   - A **conventional commit PR title** (e.g. `feat: add zoom controls`, `fix: character freezing on terminal close`, `refactor: extract pathfinding module`). CI enforces this format — see [Conventional Commits](https://www.conventionalcommits.org/).
    - A clear description of what changed and why
    - How you tested the changes (steps to reproduce / verify)
    - **Screenshots or GIFs for any UI changes**
 
+> **Note:** PRs are merged using **squash and merge** — all commits in your PR are combined into a single commit on `main`. Your PR title becomes the commit message, which is why the conventional commit format matters.
+
 ## Reporting Bugs
 
-[Open a bug report](https://github.com/pablodelucca/pixel-agents/issues/new?template=bug_report.yml) — the form will guide you through providing the details we need.
+[Open a bug report](https://github.com/DavidUmKongs/oh-my-pixel-agents/issues/new?template=bug_report.yml) — the form will guide you through providing the details we need.
 
 ## Feature Requests
 
-Have an idea? [Start a discussion](https://github.com/pablodelucca/pixel-agents/discussions/categories/ideas) in the Ideas category. We love hearing new ideas, and discussing them first helps us collaborate on the best approach together.
+Have an idea? [Open a feature request](https://github.com/DavidUmKongs/oh-my-pixel-agents/issues/new?template=feature_request.yml) — the form will guide you through describing the problem and your proposed solution. You can also browse and join ongoing conversations in [Discussions](https://github.com/DavidUmKongs/oh-my-pixel-agents/discussions).
 
 ## Security Issues
 

README.ko.md

@@ -158,7 +158,7 @@ Pixel Agents는 선택된 백엔드의 JSONL transcript 파일을 감시해서 
 
 ## 커뮤니티와 기여
 
-질문, 아이디어, 논의는 **[GitHub Discussions](https://github.com/pablodelucca/pixel-agents/discussions)** 에서 진행합니다. **[Issues](https://github.com/pablodelucca/pixel-agents/issues)** 는 버그 리포트 전용입니다.
+질문, 아이디어, 논의는 **[GitHub Discussions](https://github.com/DavidUmKongs/oh-my-pixel-agents/discussions)** 에서 진행합니다. **[Issues](https://github.com/DavidUmKongs/oh-my-pixel-agents/issues)** 는 버그 리포트 전용입니다.
 
 기여 방법은 [CONTRIBUTING.md](CONTRIBUTING.md)를 참고해 주세요.
 

README.md

@@ -46,6 +46,7 @@ This repository tracks the `oh-my-pixel-agents` fork of Pixel Agents for VS Code
 - **Sound notifications** — optional chime when an agent finishes its turn
 - **Sub-agent visualization** — Task tool sub-agents spawn as separate characters linked to their parent
 - **Persistent layouts** — your office design is saved and shared across VS Code windows
+- **External asset directories** — load custom or third-party furniture packs from any folder on your machine
 - **Diverse characters** — 6 diverse characters. These are based on the amazing work of [JIK-A-4, Metro City](https://jik-a-4.itch.io/metrocity-free-topdown-character-pack).
 - **Agent inspector** — click an agent to open a pinned inspector showing its current tool, confidence, permission state, and recent timeline without jumping to the terminal.
 - **Timeline debug view** — toggle Debug mode to see each agent’s tool calls, sub-agent branches, and permission waits rendered as rails with duration/approval badges.
@@ -125,7 +126,7 @@ Each furniture item lives in its own folder under `assets/furniture/` with a `ma
 
 To add a new furniture item, create a folder in `webview-ui/public/assets/furniture/` with your PNG sprite(s) and a `manifest.json`, then rebuild. The asset manager (`scripts/asset-manager.html`) provides a visual editor for creating and editing manifests.
 
-Detailed documentation on the manifest format and asset pipeline is coming soon.
+To use furniture from an external directory, open Settings → **Add Asset Directory**. See [docs/external-assets.md](docs/external-assets.md) for the full manifest format and how to use third-party asset packs.
 
 Characters are based on the amazing work of [JIK-A-4, Metro City](https://jik-a-4.itch.io/metrocity-free-topdown-character-pack).
 
@@ -163,14 +164,12 @@ For this to work, the architecture needs to be modular at every level:
 - **Agent-agnostic**: Claude Code today, but built to support Codex, OpenCode, Gemini, Cursor, Copilot, and others through composable adapters.
 - **Theme-agnostic**: community-created assets, skins, and themes from any contributor.
 
-We're actively working on the core module and adapter architecture that makes this possible. If you're interested to talk about this further, please visit our [Discussions Section](https://github.com/pablodelucca/pixel-agents/discussions).
+We're actively working on the core module and adapter architecture that makes this possible. If you're interested to talk about this further, please visit our [Discussions Section](https://github.com/DavidUmKongs/oh-my-pixel-agents/discussions).
 
 
 ## Community & Contributing
 
-We use **[GitHub Discussions](https://github.com/pablodelucca/pixel-agents/discussions)** for questions, feature ideas, and conversations. **[Issues](https://github.com/pablodelucca/pixel-agents/issues)** are for bug reports only.
-
-If something is broken, open an issue. For everything else, start a discussion.
+Use **[Issues](https://github.com/DavidUmKongs/oh-my-pixel-agents/issues)** to report bugs or request features. Join **[Discussions](https://github.com/DavidUmKongs/oh-my-pixel-agents/discussions)** for questions and conversations.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on how to contribute.