netclaw-dev · Aaronontheweb · Jul 14, 2026 · Jul 11, 2026 · Jul 11, 2026 · Jul 11, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -307,6 +307,11 @@ consider model capability as the cause.
 
 ## System Skills Sync Rule
 
+Runtime skill use is logical: call `skill_load` by canonical name and
+`skill_read_resource` for bundled files. Do not expose physical skill roots in
+prompt indexes or teach agents to derive `SKILL.md` paths. Direct filesystem
+inspection is reserved for explicit operator diagnostics.
+
 System skills in `feeds/skills/.system/files/` are the agent's operational
 guidance — they tell the running agent how to use features. When you change a
 feature area, the corresponding skill **must** be updated in the same PR.

diff --git a/Directory.Build.props b/Directory.Build.props
@@ -9,21 +9,13 @@
     <Nullable>enable</Nullable>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <VersionPrefix>0.25.0</VersionPrefix>
-    <VersionSuffix>alpha.onnx.5</VersionSuffix>
-    <PackageReleaseNotes>Netclaw v0.25.0-beta.1 — SkillServer native sub-agent sync, memory curation unification, systemd PATH fix
-
-**Features**
-
-* **SkillServer native sub-agent sync** — Optional native manifest sidecar sync for server-managed sub-agents. Local sub-agent files load before server-feed files so user-authored definitions always win. ([#1539](https://github.com/netclaw-dev/netclaw/pull/1539))
-
-**Bug Fixes**
-
-* **Systemd shell tool PATH** — Fixed: daemon now captures the operator's full PATH into the systemd EnvironmentFile instead of relying on a hardcoded list. ([#1565](https://github.com/netclaw-dev/netclaw/pull/1565))
-
-**Memory**
-
-* **Shared curation evaluator** — Unified curation logic across both memory write pipelines so they can never diverge again. ([#1575](https://github.com/netclaw-dev/netclaw/pull/1575))
-* **Memory audit quick wins** — July 2026 audit: revived curation LLM, balanced prompt, and recall precision re-tune. ([#1568](https://github.com/netclaw-dev/netclaw/pull/1568))</PackageReleaseNotes>
+    <VersionSuffix>alpha.onnx.6</VersionSuffix>
+    <PackageReleaseNotes>- Preserve Git working context across sessions and subagents — A bounded, audience-aware Git working-context snapshot stays current in the system prompt, and coding subagents inherit recent-file/project context (#1630)
+- User-written AGENTS.md for application-specific agent guidance — Operators can author ~/.netclaw/identity/AGENTS.md, layered after Netclaw's embedded operating core and inherited by sub-agents (#1622)
+- Memory curation no longer overwrites existing documents on collision — Create-decision collisions now append new content instead of silently overwriting the existing document (#1637)
+- STDIO MCP server arguments no longer rewritten — The daemon now preserves configured STDIO MCP server arguments, and uses one daemon-owned client per configured MCP server (#1636)
+- Logical skill access and authoritative inventory refresh — Skill loading now resolves through logical skill_load/skill_read_resource access with native &gt; managed-feed &gt; external precedence (#1634)
+- Bump SkillServer to stable — Netclaw.SkillClient 0.4.0-beta.4 → 0.4.0 (#1638)</PackageReleaseNotes>
   </PropertyGroup>
   <PropertyGroup>
     <NetCoreTestVersion>net10.0</NetCoreTestVersion>

diff --git a/Directory.Packages.props b/Directory.Packages.props
@@ -68,7 +68,7 @@
     <PackageVersion Include="SlackNet" Version="$(SlackNetVersion)" />
     <PackageVersion Include="SlackNet.Extensions.DependencyInjection" Version="$(SlackNetVersion)" />
     <PackageVersion Include="Cronos" Version="0.13.0" />
-    <PackageVersion Include="Netclaw.SkillClient" Version="0.4.0-beta.4" />
+    <PackageVersion Include="Netclaw.SkillClient" Version="0.4.0" />
     <PackageVersion Include="ShellSyntaxTree" Version="0.1.5" />
     <PackageVersion Include="Termina" Version="0.15.0" />
   </ItemGroup>

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -1,5 +1,38 @@
 # NetClaw Release Notes
 
+## 0.25.0-alpha.onnx.6 (2026-07-14)
+
+> Experimental ONNX local-embeddings build. Syncs `feature/memory-embeddings` with `dev`
+> through 0.25.0-beta.4. No changes to memory/embeddings behavior in this release — this is
+> a mainline sync only. Everything still rides `Memory.Embeddings.Enabled`, off by default;
+> install only by exact pin (`NETCLAW_VERSION=0.25.0-alpha.onnx.6`).
+
+### Features
+- **Preserve Git working context across sessions and subagents** — a bounded, audience-aware Git working-context snapshot stays current in the system prompt, and coding subagents inherit recent-file/project context so parent sessions merge back only confirmed successful child edits ([#1630](https://github.com/netclaw-dev/netclaw/pull/1630))
+
+### Bug Fixes
+- **Curation dedup no longer overwrites existing memories** — a Create-decision anchor collision now appends below a dated separator instead of silently replacing the document; verbatim duplicates are skipped. ([#1637](https://github.com/netclaw-dev/netclaw/pull/1637))
+- **STDIO MCP server arguments no longer rewritten** — the daemon now preserves configured STDIO MCP server arguments, and uses one daemon-owned client per configured MCP server ([#1636](https://github.com/netclaw-dev/netclaw/pull/1636))
+
+### Improvements
+- **Logical skill access and authoritative inventory refresh** — skill loading now resolves through logical `skill_load`/`skill_read_resource` access with native > managed-feed > external precedence ([#1634](https://github.com/netclaw-dev/netclaw/pull/1634))
+
+## 0.25.0-beta.4 (2026-07-14)
+
+### Features
+- **Preserve Git working context across sessions and subagents** — A bounded, audience-aware Git working-context snapshot (branch, worktree, repository, upstream, changed files) now stays current in the system prompt, and coding subagents inherit recent-file/project context so parent sessions merge back only confirmed successful child edits. Measured 20% → 100% success rate on a linked-worktree coding eval ([#1630](https://github.com/netclaw-dev/netclaw/pull/1630))
+- **User-written `AGENTS.md` for application-specific agent guidance** — Operators can now author `~/.netclaw/identity/AGENTS.md`, layered after Netclaw's embedded operating core and inherited by sub-agents, to give the running agent deployment-specific mission and workflow guidance. Seeded with a minimal scaffold during init without overwriting existing guidance ([#1622](https://github.com/netclaw-dev/netclaw/pull/1622))
+
+### Bug Fixes
+- **Memory curation no longer overwrites existing documents on collision** — Fixed: when a curation Create decision targeted an anchor that already had a document, the write silently overwrote the existing title, body, and classification with no history — observed 88 times in 14 days in production, including one case that destroyed an LLM-merged document. Collisions now append the new content under a dated separator instead of overwriting; a verbatim duplicate is skipped as a no-op ([#1637](https://github.com/netclaw-dev/netclaw/pull/1637))
+- **STDIO MCP server arguments no longer rewritten** — Fixed: configured STDIO MCP server arguments were being rewritten by the daemon; the daemon now preserves them as configured. Also simplified to one daemon-owned client per configured MCP server, removing Playwright-specific session-scoped process handling ([#1636](https://github.com/netclaw-dev/netclaw/pull/1636))
+
+### Improvements
+- **Logical skill access and authoritative inventory refresh** — Skill loading now resolves through logical `skill_load`/`skill_read_resource` access instead of physical skill-root paths, with native > managed-feed > external precedence. Startup, sync, watcher, and `skill_manage` inventory rebuilds are now centralized through one live-source refresher publishing atomic registry snapshots ([#1634](https://github.com/netclaw-dev/netclaw/pull/1634))
+
+### Dependency Updates
+- **Bump SkillServer to stable** — `Netclaw.SkillClient` 0.4.0-beta.4 → 0.4.0 (stable release) ([#1638](https://github.com/netclaw-dev/netclaw/pull/1638))
+
 ## 0.25.0-alpha.onnx.5 (2026-07-12)
 
 > **Experimental feature build** (fifth in the memory-embeddings series). This build carries
@@ -23,6 +56,18 @@
 - MessagePack 3.1.7 → 3.1.8 ([#1605](https://github.com/netclaw-dev/netclaw/pull/1605))
 - .NET SDK 10.0.300 → 10.0.301 ([#1381](https://github.com/netclaw-dev/netclaw/pull/1381))
 
+## 0.25.0-beta.3 (2026-07-12)
+
+### Features
+- **Discord DM reminder delivery** — Reminders can now be delivered to Discord DMs via improved `DiscordReminderTargetResolver` ([#1609](https://github.com/netclaw-dev/netclaw/pull/1609))
+- **Named model configuration & provider runtime validation** — New `NamedModelConfiguration` and `ProviderRuntimeValidation` types, config schema updates, and CLI wizard improvements for provider/model setup ([#1610](https://github.com/netclaw-dev/netclaw/pull/1610))
+
+### Bug Fixes
+- **Model set/picker preserves hand-set modalities** — Re-selecting the same model no longer wipes operator-set `InputModalities`/`OutputModalities` and `ContextWindow`. Added `--input-modalities`, `--output-modalities`, `--clear-modalities`, and `--clear-context-window` CLI flags ([#1610](https://github.com/netclaw-dev/netclaw/pull/1610))
+- **Slack processing status serialization** — Slack processing status updates are now serialized to prevent race conditions during concurrent sends ([#1556](https://github.com/netclaw-dev/netclaw/pull/1556))
+- **Sub-agent token usage tracked in daily stats** — Sub-agent LLM calls now record token usage, making them visible in `netclaw stats` ([#1597](https://github.com/netclaw-dev/netclaw/pull/1597))
+- **Subagents fail closed for unattended approvals** — When a subagent requires approval but the session is unattended, it now fails closed instead of proceeding or hanging ([#1616](https://github.com/netclaw-dev/netclaw/pull/1616))
+
 ## 0.25.0-alpha.onnx.4 (2026-07-09)
 
 > **Experimental feature build** (fourth in the memory-embeddings series). Same gating:

diff --git a/docs/prd/PRD-004-cli-onboarding-and-config.md b/docs/prd/PRD-004-cli-onboarding-and-config.md
@@ -61,7 +61,8 @@ Fresh-install flow:
 1. LLM provider configuration (endpoint URL, API key or OAuth device flow,
    model selection, connectivity test)
 2. Identity setup (workspaces directory, user name, timezone) with init-owned
-   regeneration of `SOUL.md` and `TOOLING.md`
+   regeneration of `SOUL.md` and `TOOLING.md` plus non-destructive seeding of
+   the deployment mission scaffold in `AGENTS.md`
 3. Security posture (`Personal`, `Team`, `Public`)
 4. Enabled Features for `Team` and `Public` only
 5. Final validation / health check / next steps
@@ -199,12 +200,18 @@ Onboarding captures all Phase 1 setup items in a stepwise flow.
 `netclaw init` SHALL support an interactive guided onboarding flow that:
 
 1. Captures LLM provider configuration (OpenRouter default, OAuth or API key)
-2. Captures init-owned identity settings and regenerates `SOUL.md` /
-   `TOOLING.md`
+2. Captures init-owned identity settings, regenerates `SOUL.md` / `TOOLING.md`,
+   and seeds `AGENTS.md` only when absent
 3. Selects security posture (`Personal`, `Team`, `Public`)
 4. Continues into Enabled Features when posture is `Team` or `Public`
 5. Runs final validation and prints next-step run commands
 
+After successful setup, the initial chat SHALL discover operator context and
+the deployment mission as separate concerns. Confirmed personality/operator
+context is persisted to `SOUL.md`; confirmed mission, recurring workflows,
+skill-selection rules, delegation practices, and review gates are persisted to
+`AGENTS.md` without overwriting an existing playbook during wizard setup.
+
 ### CLI-001B Post-Install Configuration
 
 `netclaw config` SHALL be the primary post-install settings surface. It SHALL:

diff --git a/docs/prd/PRD-006-mcp-tool-integration.md b/docs/prd/PRD-006-mcp-tool-integration.md
@@ -94,6 +94,13 @@ Runtime SHALL degrade gracefully when MCP server is unavailable:
 - Reconnection is attempted on next tool call
 - Diagnostics flag the outage
 
+### MCP-009 Daemon-Bound Server Ownership
+
+Each configured MCP server SHALL have at most one live client connection per
+Netclaw daemon. A local STDIO server process and its internal state are shared
+by all sessions authorized to use that server; Netclaw session identity SHALL
+not launch or select a separate MCP process.
+
 ## Non-Goals (MVP)
 
 - Dynamic marketplace discovery of MCP servers
@@ -110,6 +117,8 @@ Runtime SHALL degrade gracefully when MCP server is unavailable:
 5. MCP tools appear in session tool definitions when server is enabled and
    granted.
 6. Unavailable MCP server does not crash the session.
+7. Calls from different authorized sessions to one local STDIO profile use the
+   same daemon-owned client and child process.
 
 ## Cross-References
 

diff --git a/docs/prd/PRD-007-agent-personality-and-local-memory.md b/docs/prd/PRD-007-agent-personality-and-local-memory.md
@@ -9,7 +9,7 @@
 
 ## Goal
 
-Define the agent soul (personality, instructions, user preferences), local
+Define the agent identity (personality, deployment mission, operator context), local
 memory system (project registry, environment inventory), capability
 self-discovery, self-configuration, and first-party tool access. This is the
 "brain" of Netclaw — everything that makes it a persistent, context-aware
@@ -25,18 +25,19 @@ agent rather than a stateless chat endpoint.
 
 ## Agent Soul Architecture
 
-### File-Based Personality (Soul Files)
+### File-Based Identity
 
-Agent identity is stored as data (markdown files), not code. The agent
-reconstructs its personality from files on every session start. This makes
-identity hot-swappable and version-controllable without code changes.
+Agent identity is stored as data (markdown files), not code. Netclaw supplies
+an embedded operating core that explains the machinery. Operator-authored files
+augment it and are re-read before each inbound turn, making deployment behavior
+hot-swappable and version-controllable without code changes.
 
 ```
 ~/.netclaw/
-  soul/
-    PERSONALITY.md     # Agent character, tone, values, boundaries
-    INSTRUCTIONS.md    # Operating rules, behavioral guidelines
-    USER.md            # Owner preferences, timezone, how to address them
+  identity/
+    SOUL.md             # Agent personality, tone, and operator context
+    AGENTS.md           # Deployment mission, workflows, skills, and quality gates
+    TOOLING.md          # Available environment capabilities
   projects/
     registry.json      # Registered project configurations
   environment/
@@ -50,25 +51,32 @@ identity hot-swappable and version-controllable without code changes.
 
 ### Layered System Prompt Assembly
 
-Session context is assembled from layers (later layers augment earlier):
+Session context is assembled from layers:
 
-1. **PERSONALITY.md** — who the agent is (values, tone, boundaries)
-2. **INSTRUCTIONS.md** — how the agent operates (rules, workflows)
-3. **USER.md** — who it serves (owner name, preferences, timezone)
-4. **Project AGENTS.md** — context overlay when working on a registered project
-5. **Environment summary** — condensed capability inventory
-6. **Session context** — conversation history, tool results, memory
+1. **SOUL.md** — who the agent is and who it serves
+2. **Embedded operating core** — how Netclaw machinery operates for the audience
+3. **Deployment AGENTS.md** — how this deployment accomplishes its mission
+4. **TOOLING.md** — what capabilities are available
+5. **Project AGENTS.md** — scoped context for the active project
+6. **Dynamic and session context** — tools, skills, memory, history, and results
+
+The same deployment playbook applies to Personal, Team, and Public audiences
+and is inherited by sub-agents. It contains durable workflow guidance only,
+never secrets or audience-private data. Embedded prompt precedence is guidance;
+runtime ACL and tool policy remain the authoritative security boundary.
 
 ### Conversational Personality Bootstrap
 
 On first interaction (or when personality files don't exist), the agent runs
 a personality bootstrap conversation:
 
 1. Introduce itself and explain the setup process
-2. Learn the owner's name, preferences, communication style
-3. Scan environment for installed tools and capabilities
-4. Write initial PERSONALITY.md, INSTRUCTIONS.md, USER.md
-5. Confirm readiness
+2. Learn the owner's name, preferences, and communication style
+3. Learn the deployment mission, successful outcomes, recurring workflows,
+   skill-selection expectations, delegation rules, and known failure modes
+4. Propose a concise mission playbook and obtain confirmation
+5. Update `SOUL.md` and `AGENTS.md` with their canonical content
+6. Confirm that the playbook applies on the next message
 
 This can be re-triggered via `netclaw personality reset` (PRD-004).
 

diff --git a/docs/spec/SPEC-007-guided-onboarding.md b/docs/spec/SPEC-007-guided-onboarding.md
@@ -27,6 +27,7 @@ existing-install re-entry paths.
 - collect user name
 - collect timezone
 - regenerate `SOUL.md` and `TOOLING.md`
+- seed a minimal deployment `AGENTS.md` scaffold only when absent
 
 ### Step 3: Security Posture
 
@@ -60,6 +61,16 @@ bootstrap flow by default. Instead it presents:
 - remains init-owned
 - reuses the identity form with existing values prefilled
 - continues into the bot-assisted identity conversation
+- never overwrites an existing deployment `AGENTS.md`
+
+### Post-Init Conversation
+
+- discovers operator/personality context for `SOUL.md`
+- discovers mission, workflows, required skills, delegation, and review gates
+  for `AGENTS.md`
+- summarizes the proposed playbook and requires confirmation before writing
+- reads and preserves existing identity-file content
+- reports that confirmed changes apply on the next inbound message
 
 ### Start Over From Scratch