feat: add MA, resource manager, bug tracker, smart ports, user guide

New features:
- Memory Architect (MA) — full AI coding assistant with blueprints, knowledge base, skills, agent delegation, workspace project scaffolds
- Resource Manager app — entity active resource tracking with task/project management
- Bug Tracker app — screenshot capture, severity tracking, markdown report export
- Smart port management — auto-detect conflicts, identify running instances, prompt before duplicates
- /ma slash command bridge — server-to-server MA integration with auto-boot
- Entity enrichment routes — personality and cognitive state endpoints
- Process manager — start/stop/health-check for MA and sub-servers

New docs:
- USER-GUIDE.md — comprehensive 24-section NekoCore OS user guide
- MA-AND-PROJECT-STRUCTURE.md — MA architecture and folder layout

Infrastructure:
- port-guard.js shared utility for all servers
- kill-all.js and neko-start.js convenience scripts
- MA workspace scaffolds (rem-system + nekocore) with build blueprints
- Gitignore hardened for MA private data (API keys, memories, chat history)
- Factory reset run for both NekoCore OS and MA — ships clean

Author: VoardWalker-Code

.gitignore

@@ -57,6 +57,45 @@ project/server/data/nekocore-audit.ndjson
 project/skills/*/workspace/*
 !project/skills/*/workspace/.gitkeep
 
+# MA private runtime data — never commit
+/project/MA/MA-Config/ma-config.json
+/project/MA/MA-Config/chat-history.json
+/project/MA/MA-Config/model-performance.json
+/project/MA/MA-Config/chores.json
+/project/MA/MA-entity/*/memories/
+/project/MA/MA-entity/*/index/
+/project/MA/MA-entity/*/archives/
+/project/MA/MA-entity/*/prompt-history/
+/project/MA/MA-logs/
+
+# MA dev/debug temp scripts — not for distribution
+/project/MA/tmp-*.js
+/project/MA/_*.js
+/project/MA/test-*.js
+
+# MA workspace projects — starter scaffolds are tracked (BUILD-ORDER.md, PROJECT-MANIFEST.json, package.json).
+# Everything MA builds inside these folders (source, tests, node_modules) is gitignored.
+# Only the scaffold files are committed — the rest is generated by MA at build time.
+/project/MA/MA-workspace/nekocore/node_modules/
+/project/MA/MA-workspace/nekocore/server/
+/project/MA/MA-workspace/nekocore/contracts/
+/project/MA/MA-workspace/nekocore/client/
+/project/MA/MA-workspace/nekocore/scripts/
+/project/MA/MA-workspace/nekocore/tests/
+/project/MA/MA-workspace/nekocore/nekocore-server.js
+/project/MA/MA-workspace/nekocore/nekocore-cli.js
+/project/MA/MA-workspace/nekocore/nekocore-start.js
+/project/MA/MA-workspace/rem-system/node_modules/
+/project/MA/MA-workspace/rem-system/server/
+/project/MA/MA-workspace/rem-system/contracts/
+/project/MA/MA-workspace/rem-system/client/
+/project/MA/MA-workspace/rem-system/config/
+/project/MA/MA-workspace/rem-system/entities/
+/project/MA/MA-workspace/rem-system/scripts/
+/project/MA/MA-workspace/rem-system/tests/
+/project/MA/MA-workspace/rem-system/rem-server.js
+/project/MA/MA-workspace/rem-system/rem-start.js
+
 # Generated system repair script (build artifact from generate-fixer.js)
 project/neko_fixer.py
 

CHANGELOG.md

@@ -197,7 +197,7 @@ The brain loop ticks independently of conversation:
 
 > **Layered cognition** — subconscious, dream-intuition, and conscious phases run in formation; parallel where it counts, sequential where it must.
 
-> **Zero dependencies** — the entire runtime is pure Node.js. No vector database. No external SDKs. File-system JSON persistence.
+> **Zero dependencies** — the entire runtime is pure Node.js (no Express, no frameworks). No vector database. No external SDKs. File-system JSON persistence.
 
 > **Open architecture** — every subsystem is observable via the SSE cognitive bus. Nothing the entity thinks is hidden from the developer.
 
@@ -207,7 +207,7 @@ The brain loop ticks independently of conversation:
 
 | Capability | Detail |
 |---|---|
-| **Runtime** | Pure Node.js 18+ — zero external runtime dependencies |
+| **Runtime** | Pure Node.js 18+ — zero external runtime dependencies (no Express) |
 | **Persistence** | File-system JSON — no database required |
 | **Memory types** | Episodic · Semantic · Long-Term (compressed chatlog chunks) |
 | **Pipeline phases** | 1A (subconscious) · 1D (dream) · 1C (conscious) · Final · Brain Loop |
@@ -335,7 +335,7 @@ npm install
 npm start
 ```
 
-Open `http://localhost:3000` in your browser.
+Open `http://localhost:3847` in your browser.
 
 ### Configure
 
@@ -349,8 +349,7 @@ cp Config/ma-config.example.json Config/ma-config.json
 {
   "provider": "ollama",
   "ollamaBaseUrl": "http://localhost:11434",
-  "defaultModel": "mistral",
-  "port": 3000
+  "defaultModel": "mistral"
 }
 ```
 
@@ -360,11 +359,12 @@ cp Config/ma-config.example.json Config/ma-config.json
 {
   "provider": "openrouter",
   "openRouterApiKey": "sk-or-...",
-  "defaultModel": "mistralai/mistral-7b-instruct",
-  "port": 3000
+  "defaultModel": "mistralai/mistral-7b-instruct"
 }
 ```
 
+The server port (default 3847) is not set in the config file — it uses `PORT` environment variable or the built-in default. If the port is busy, the server identifies what's running and offers to start on the next available port.
+
 ### Recommended Multi-Phase Setup
 
 Route each pipeline phase to a specialized model for best results:

README.md

@@ -1,7 +1,7 @@
 # REM System — Architecture Overview
 
-Version: 0.9.0
-Last updated: 2026-03-18
+Version: 0.10.0
+Last updated: 2026-03-22
 
 ---
 
@@ -22,6 +22,12 @@ Phases 1–3 (bug fixes, refactor, modularization) are complete. Feature work is
 - **Phase 4.7 — Agent Echo: Multi-Index Archive + Retrieval Pipeline:** ✅ COMPLETE — Echo Now + Echo Past retrieval behavior integrated.
 - **Phase 4.8 — Pipeline Hardening + Modularization Completion:** ✅ COMPLETE.
 - **Phase 4.9 — Modular Task Orchestration Architecture (MTOA):** ✅ COMPLETE — task intent fork, context gatherer, executor/event bus, sessions/archive/project store, frontman bridge, task routes, entity-chat planning, and client task UI are live.
+- **Phase 4.10 — Entity Orchestration:** ✅ COMPLETE — multi-entity session API and planning infrastructure.
+- **OS Tool System Upgrade:** ✅ COMPLETE — three-pass JSON/Zod parser replaces regex, block format for file writes, structured result formatting.
+- **Entity Genesis Skill:** ✅ COMPLETE — MA-driven entity creation with iterative memory injection and cognitive ticking.
+- **MA Bridge:** ✅ COMPLETE — `/ma` slash command for server-to-server MA calls with auto-boot.
+- **Bug Tracker App:** ✅ COMPLETE — developer bug tracking with screenshots, JSON persistence, markdown reports.
+- **Resource Manager App:** ✅ COMPLETE — unified GUI for Todos, Pulses, Tasks, Projects, and Blueprints with CRUD, active-state toggling, and MA pulse proxy.
 - **Installer package baseline (pre-cleanup):** ✅ COMPLETE — strict marker-boundary installer/uninstaller, rollback guarantees, `JsonEntryId` targeting, and app payload file lifecycle (`create-file`, `delete-file`) validated with Hello World end-to-end.
 - **Phase 5 — Predictive Memory Topology:** next approved feature phase.
 
@@ -63,6 +69,13 @@ Desktop shell, browser, and runtime stability work continues in parallel with Ph
 | **Skills** | skills/ | Pluggable tools (web search, file ops, memory tools) |
 | **SSE / Diagnostics** | server/routes/sse-routes.js | Real-time streaming diagnostics and cognitive bus events |
 | **Task UI (Client)** | client/js/apps/optional/task-ui.js, client/js/apps/core/chat.js, client/js/apps/core/telemetry-ui.js | Task badge/status in chat, task history/detail panel, Task Manager active-task telemetry |
+| **MA Bridge** | server/services/ma-bridge.js | Server-to-server calls to MA (port 3850) with auto-boot via process manager |
+| **Process Manager** | server/routes/process-manager-routes.js | Start/stop/health-check for MA, REM System, and NekoCore servers |
+| **Entity Enrichment** | server/routes/entity-enrichment-routes.js | Memory injection, cognitive tick, and state read for external builders (Entity Genesis) |
+| **Todo Store** | server/services/todo-store.js | Per-entity todo CRUD with atomic disk writes |
+| **Resource Active State** | server/services/resource-active-state.js | Tracks which todo/task/project/pulse is "active" per entity |
+| **Resource Manager Routes** | server/routes/resource-manager-routes.js | REST API for todos, tasks, projects, blueprints, MA pulse proxy, and active state |
+| **Bug Tracker (Client)** | client/apps/non-core/core/tab-bugtracker.html | Developer bug tracking app with screenshot capture and reporting |
 
 ---
 
@@ -96,13 +109,20 @@ server/routes/
   task-routes.js         — task run/session/cancel/modules/history API
   entity-chat-routes.js  — planning/multi-entity chat session API
   entity-routes.js       — entity CRUD, user profiles, relationships, guided/character creation
+  entity-enrichment-routes.js — memory injection, cognitive tick, state read (Entity Genesis)
   memory-routes.js       — memory read/write/search
   brain-routes.js        — brain loop control
   cognitive-routes.js    — sleep, dream, archive triggers
   document-routes.js     — document ingestion pipeline
   config-routes.js       — runtime config management
   sse-routes.js          — real-time event streaming
   skills-routes.js       — skill invocation surface
+  browser-routes.js      — embedded browser session management
+  vfs-routes.js          — virtual filesystem operations
+  nekocore-routes.js     — NekoCore OS system routes
+  archive-routes.js      — conversation archive management
+  process-manager-routes.js — MA/REM/NekoCore server lifecycle
+  resource-manager-routes.js — todos, tasks, projects, pulses, blueprints, active state
 ```
 
 ---
@@ -117,6 +137,7 @@ entities/
     onboarding-state.json
     beliefs/             — belief graph persistence
     index/               — memory index files
+    active-resources.json — tracks which todo/task/project/pulse is currently active
     memories/
       context.md         — assembled LLM context (rebuilt on server start and memory update)
       system-prompt.txt  — identity foundation and backstory
@@ -125,6 +146,7 @@ entities/
       episodic/          — episodic memory folders
       semantic/          — semantic knowledge folders
       ltm/               — long-term compressed chatlog chunks
+      todos/             — per-entity todo items (todos.json)
     quarantine/
     skills/
 ```
@@ -136,11 +158,15 @@ entities/
 | File | Contents |
 |------|----------|
 | ARCHITECTURE-OVERVIEW.md | This file — system map and design principles |
+| USER-GUIDE.md | Complete NekoCore OS user guide — desktop, apps, entities, chat, brain, memory, dreams, LLM setup |
+| MA-AND-PROJECT-STRUCTURE.md | MA's role, folder relationship, gitignored builds, sub-project history |
 | PIPELINE-AND-ORCHESTRATION.md | Cognitive pipeline, orchestrator, worker subsystem, escalation |
 | MEMORY-SYSTEM.md | All memory subsystems — storage, retrieval, decay, belief graph, topic archive, context assembly |
 | ENTITY-AND-IDENTITY.md | Entity creation, identity modes, voice profiles, context consolidation |
 | DREAM-SYSTEM.md | Dream intuition (live) and dream maintenance (offline sleep) |
 | CONTRACTS-AND-SCHEMAS.md | Memory schema, voice profile schema, worker output contract, contributor contracts |
 | MODEL-RECOMMENDATIONS.md | OpenRouter + Ollama model picks for each pipeline stage |
+| HOW-TO-CREATE-AN-APP.md | Step-by-step guide for building new NekoCore OS apps |
+| APP-FOLDER-OWNERSHIP.md | File ownership rules for client apps |
 | NEKOCORE-OS-WHITE-PAPER-v2.md | Technical white paper — architecture, philosophy, and benchmark results |
 | NEKOCORE-OS-ARCHITECTURE-v1.md | Deep technical reference — full subsystem coverage, file map, ADRs |

WORKLOG.md

@@ -0,0 +1,138 @@
+# MA and Project Structure
+
+Version: 1.0.0
+Last updated: 2026-03-22
+
+---
+
+## Why MA Lives Inside the Project
+
+**MA (Memory Architect)** is NekoCore OS's built-in AI development agent. It is not an external dependency — it is a first-class subsystem that lives at `project/MA/` and serves two roles:
+
+1. **Builder** — MA's blueprints define the architecture for two sub-projects that can be built from scratch:
+   - **REM System Core** (26 modules, 8 layers) — the cognitive memory engine at port 3860
+   - **NekoCore Cognitive Mind** (97 modules, 5 parts) — the full cognitive personality runtime at port 3870
+
+   Starter scaffolds (PROJECT-MANIFEST.json, BUILD-ORDER.md, package.json) are included in the repo. MA builds the full implementation from the blueprints.
+
+2. **Runtime service** — MA runs as a persistent background server (port 3850) that NekoCore OS entities can call for tool execution, web search, model routing, and recurring task management (pulses/chores). The OS server proxies requests to MA through the `/ma` slash command bridge and the Resource Manager's pulse panel.
+
+### Folder Relationship
+
+```
+project/
+├── server/           ← NekoCore OS server (port 3847)
+│   └── brain/        ← Cognitive pipeline, tasks, blueprints
+├── client/           ← OS GUI (desktop shell, apps, tabs)
+├── MA/               ← Memory Architect (port 3850)
+│   ├── MA-Server.js  ← Self-contained Node.js server
+│   ├── MA-server/    ← 15 core modules (zero npm deps)
+│   ├── MA-workspace/ ← Sandboxed project workspace
+│   │   ├── nekocore/    ← Starter scaffold (MA builds from blueprints)
+│   │   └── rem-system/  ← Starter scaffold (MA builds from blueprints)
+│   ├── MA-blueprints/   ← Build instructions (tracked)
+│   ├── MA-knowledge/    ← Reference docs (tracked)
+│   └── MA-skills/       ← Skill definitions (tracked)
+├── entities/         ← [GITIGNORED] Runtime entity data
+└── memories/         ← [GITIGNORED] Runtime system memory
+```
+
+MA itself (the engine, config templates, blueprints, skills, knowledge base) is **tracked in git**. The workspace projects include starter scaffolds (manifest, build order, package.json) that are tracked — everything MA builds from the blueprints (source code, tests, node_modules) is gitignored.
+
+### How the Workspace Projects Work
+
+The `nekocore/` and `rem-system/` workspace directories ship as **starter scaffolds** — just a PROJECT-MANIFEST.json (all statuses "not-started"), a BUILD-ORDER.md (construction guide), and a package.json. MA reads the blueprints (`MA-blueprints/nekocore/` and `MA-blueprints/rem-system/`) and builds the full implementation module-by-module, updating the manifest as it goes.
+
+The generated source code, contracts, tests, client code, and node_modules are all gitignored. The blueprints remain tracked and serve as the authoritative build instructions.
+
+---
+
+## How MA Communicates With NekoCore OS
+
+### Server-to-Server Bridge
+
+NekoCore OS entities can call MA through the `/ma` slash command:
+
+```
+User: /ma search for Node.js best practices
+```
+
+The OS server (`server/services/ma-bridge.js`) handles this by:
+1. Checking if MA is running (health check on port 3850)
+2. Auto-booting MA via the process manager if offline
+3. Sending the message to `POST /api/chat` on MA
+4. Returning MA's response to the entity's conversation
+
+### Pulse/Chore Proxy
+
+The Resource Manager app proxies pulse and chore management through the OS server:
+
+```
+Client → OS Server (port 3847)     → MA Server (port 3850)
+GET /api/resources/pulses           → GET /api/pulse/status + GET /api/chores/list
+POST /api/resources/pulses/chores   → POST /api/chores/add
+POST /api/resources/pulses/:id/toggle → POST /api/pulse/start or /api/pulse/stop
+```
+
+This keeps the client talking to a single origin (the OS server) while MA handles the recurring task engine internally.
+
+### Process Management
+
+The OS server can start, stop, and health-check both MA and the NekoCore Cognitive Mind server via the Process Manager routes:
+
+| Route | Action |
+|-------|--------|
+| `GET /api/servers/status` | Health check all managed servers |
+| `POST /api/servers/:id/start` | Start MA or NekoCore server |
+| `POST /api/servers/:id/stop` | Stop a managed server |
+
+Managed servers: `rem-system` (port 3860), `nekocore` (port 3870), and MA itself (port 3850).
+
+---
+
+## Sub-Project Build History
+
+### REM System Core
+
+- **Location:** `MA-workspace/rem-system/` (starter scaffold tracked; built source gitignored)
+- **Blueprint:** `MA-blueprints/rem-system/` (tracked)
+- **Scope:** 26 modules across 8 layers — memory storage, NLP, pipeline, entity identity, dream/brain loop, integration, transport, entity management
+- **Port:** 3860
+- **Purpose:** Standalone cognitive memory engine that can be embedded or run as a microservice
+
+### NekoCore Cognitive Mind
+
+- **Location:** `MA-workspace/nekocore/` (starter scaffold tracked; built source gitignored)
+- **Blueprint:** `MA-blueprints/nekocore/` (tracked)
+- **Scope:** 97 modules across 5 parts — Foundation, Memory+Knowledge, Cognition Engine, Identity+Generation, Services+Transport
+- **Port:** 3870
+- **Pre-requisite:** REM System must be running (port 3860)
+- **Purpose:** Full cognitive personality runtime — the reference implementation of a NekoCore entity mind as a standalone server
+
+Both projects are built by MA following the blueprint-driven development workflow: plan → decompose → build module-by-module → test → integrate. The repo ships starter scaffolds; ask MA to build them.
+
+---
+
+## Building New Projects With MA
+
+MA's workspace (`MA-workspace/`) is sandboxed — all file operations are restricted to this directory. To create a new project:
+
+1. Write a blueprint in `MA-blueprints/` describing the architecture
+2. Start MA (`node MA-Server.js` or via Process Manager)
+3. Give MA the build instruction: `"Build the project following the blueprint at MA-blueprints/my-project/"`
+4. MA will create the project directory, scaffold modules, write tests, and iterate
+
+The blueprint system supports both core blueprints (universal patterns like task decomposition, error recovery) and module-specific blueprints (research, code, writing, analysis, planning).
+
+---
+
+## Related Documents
+
+| Document | What It Covers |
+|----------|---------------|
+| [ARCHITECTURE-OVERVIEW.md](ARCHITECTURE-OVERVIEW.md) | Full system map, subsystem table, design principles |
+| [PIPELINE-AND-ORCHESTRATION.md](PIPELINE-AND-ORCHESTRATION.md) | Cognitive pipeline, orchestrator, task fork |
+| [APP-FOLDER-OWNERSHIP.md](APP-FOLDER-OWNERSHIP.md) | File ownership rules for apps |
+| [HOW-TO-CREATE-AN-APP.md](HOW-TO-CREATE-AN-APP.md) | Step-by-step guide for new NekoCore OS apps |
+| `project/MA/README.md` | MA quick start, feature list, configuration |
+| `project/MA/USER-GUIDE.md` | Full MA user guide |