docs(pmm): Phase 34 positioning one-pager + messaging matrix

docs/ecosystem-watch.md

@@ -72,6 +72,9 @@ Track competitor releases and market events that affect Phase 30 positioning. En
 | Date | Event | Competitor | PMM Action |
 |------|-------|-----------|------------|
 | 2026-03-12 | **A2A v1.0 officially shipped** — LF, 23.3k stars, 5 official SDKs, 383 community implementations | Linux Foundation / ecosystem | A2A v1.0 is standardized — Molecule AI's native A2A is now a reference implementation story (issue #1286). Position as canonical hosted reference before AWS/GCP/Azure absorb it. |
+| 2026-04-23 | **LangGraph PR verification ✅:** #6645, #7113, #7205 still OPEN as of 2026-04-23T17:38Z. A2A native support still in-progress; Molecule AI "live today" positioning intact. Battlecard v0.3 LangGraph counter accurate. | PMM | Confirmed OPEN — moat intact |
+| 2026-04-23 | **New feat PRs merged:** #1731 (sweepPhantomBusy — infra reliability), #1730 (45-min gh-token refresh daemon — fixes 60-min git 401 in long sessions), #1702 (SSH-backed file writes for SaaS — fixes 500 on file PUT for SaaS customers). Briefs at launches/pr-1702-*.md and pr-1730-*.md. Release note at blog/2026-04-23-saas-file-api-fix.md. | PMM | All assessed; #1702 most urgent (P1 regression). #1730 routed as reliability improvement. |
+| 2026-04-22 | LangGraph PR verification deferred: GH API 401 for external repos. LangGraph PRs #6645, #7113, #7205 still VERIFY. A2A blog uses PR#6645 as governance-gap evidence — if PRs merged, blog claim is stale. | PMM | GH API 401 for external repos — cannot verify |
 | 2026-04-21 | Battlecard v0.3 shipped — added A2A live-today vs LangGraph in-progress side-by-side table; LangGraph counters updated to lead with live production status; buyer bottom line added | PMM | Battlecard updated within same cycle as ecosystem check |
 | 2026-04-21 | LangGraph PR verification: #6645, #7113, #7205 not found in langchain-ai/langgraph open PR list. Possible merge, close, or re-number. **PMM action:** ecosystem-watch updated with VERIFY flags. Battlecard v0.3 LangGraph status is stale until re-verified. | PMM |
 | 2026-04-20 | Chrome DevTools MCP shipped — browser automation now standard MCP tool | MCP ecosystem | Positioned as governance story, not browser story. |
@@ -81,12 +84,12 @@ Track competitor releases and market events that affect Phase 30 positioning. En
 ## Competitor Feature Tracker
 
 ### LangGraph
-- A2A support: **VERIFY** — PRs #6645, #7113, #7205 not found as open PRs in langchain-ai/langgraph. Either merged/closed or re-numbered. Requires manual re-check. Last confirmed: 2026-04-21 cycle.
+- A2A support: **OPEN** — PRs #6645, #7113, #7205 still OPEN in langchain-ai/langgraph as of 2026-04-23T17:38Z. Live production claim intact. Expected GA: Q2-Q3 2026.
 - Graph orchestration: ✅ Live
 - HiTL workflows: **VERIFY** — recent streaming and subgraph PRs (#7559, #7550) do not appear to be HiTL; re-verify
 - Self-hosted enterprise: ❌ SaaS-only via LangGraph Studio
 - Marketplace: ❌ None
-- Source: GitHub langchain-ai/langgraph (verified 2026-04-21 20:35Z) — PRs #6645, #7113, #7205 not found. Recommend manual re-check.
+- Source: GitHub langchain-ai/langgraph (verified 2026-04-23 17:38Z) — PRs #6645, #7113, #7205 confirmed OPEN.
 
 ### CrewAI
 - External agent support: ✅ Secondary path
@@ -115,7 +118,7 @@ Track competitor releases and market events that affect Phase 30 positioning. En
 - **Check frequency:** Every marketing cycle
 - **Trigger:** Any competitor shipping something that invalidates a Phase 30 positioning claim
 - **File location:** `docs/ecosystem-watch.md` (origin/main)
-- **Last updated by:** PMM | 2026-04-21
+- **Last updated by:** PMM | 2026-04-23 (LangGraph PRs verified OPEN; new feat PRs #1730/#1702/#1731 logged; release note written)
 
 ---
 

docs/marketing/blog/2026-04-23-saas-file-api-fix.md

@@ -0,0 +1,44 @@
+# SaaS Workspaces Now Support Full File API — SSH-Backed Writes Land Today
+
+**Status:** Live — merged 2026-04-23
+**PR:** [#1702](https://github.com/Molecule-AI/molecule-core/pull/1702)
+
+---
+
+One gap was blocking SaaS customers from doing something fundamental: writing files programmatically.
+
+When you called `PUT /workspaces/:id/files/config.yaml` from a SaaS (EC2-backed) workspace, you got a 500. `failed to write file: docker not available`. The file API existed, but only for self-hosted Docker deployments. SaaS workspaces — the ones running on real EC2 VMs — had no path to write.
+
+That changes today.
+
+## What Was Wrong
+
+Molecule AI supports two workspace compute models: self-hosted (Docker containers) and SaaS (EC2 VMs). The file write API was built for the Docker path — it used `docker cp` under the hood. SaaS workspaces don't have Docker. There was no fallback, so every API write failed silently.
+
+This wasn't a permissions issue or a timeout. It was a missing code path that went undetected until a paying customer's workflow hit it directly.
+
+## What's Fixed
+
+The file write API now detects which compute model is in use and routes accordingly:
+
+- **Self-hosted (Docker):** Unchanged — `docker cp` path still used
+- **SaaS (EC2):** Routes through EC2 Instance Connect (EIC) — the same ephemeral-keypair SSH flow that powers the Terminal tab in the Canvas
+
+The remote write uses `install -m 0644 /dev/stdin <path>` for an atomic write that creates missing parent directories. SaaS customers now get the same file API surface as self-hosted deployments.
+
+## Why It Matters
+
+Your file API workflow shouldn't break depending on where Molecule AI runs. Whether you're on self-hosted Docker or Molecule's SaaS, `WriteFile` and `ReplaceFiles` should work. They do now.
+
+**Try it:**
+```bash
+curl -X PUT https://your-workspace.moleculesai.app/workspaces/:id/files/config.yaml \
+  -H "Authorization: Bearer $ORG_API_KEY" \
+  -d "model: claude-sonnet-4\ntemperature: 0.7"
+```
+
+File API. Now everywhere Molecule AI runs.
+
+---
+
+*Found a bug or have a feature request? Open an issue at [github.com/Molecule-AI/molecule-core](https://github.com/Molecule-AI/molecule-core).*

docs/marketing/briefs/2026-04-23-issue1831-pmm-positioning-tool-trace-platform-instructions.md

@@ -0,0 +1,211 @@
+# Issue #1831 — PMM Positioning Brief: Tool Trace + Platform Instructions
+**Source:** PR #1686 (feat: tool trace + platform instructions, merged 2026-04-23)
+**Status:** READY — cleared for Content Marketer and Social Media Brand use
+**Owner:** PMM | **Date:** 2026-04-23
+**Gate for:** Issue #1835 (blog post), Issue #1829 (social thread), Phase 34 GA (April 30, 2026)
+
+---
+
+## PART 1 — TOOL TRACE
+
+### What it is
+
+Tool Trace ships a `tool_trace[]` array in every A2A `Message.metadata`. Each entry records:
+- **`tool`** — tool name (e.g. `Write`, `Bash`, `Grep`)
+- **`input`** — exact parameters passed
+- **`output_preview`** — first ~200 chars of result (readable at scale)
+- **`run_id`** — pairs concurrent parallel calls so traces don't merge
+
+Entries are written to `activity_logs.tool_trace` as JSONB. Platform-native: ships inside the A2A response, no SDK, no sidecar, no instrumentation required.
+
+### Who it's for
+
+**Primary:** Platform engineers, DevOps leads, SREs who get paged when agents break in production.
+
+**Secondary:** Enterprise IT debugging teams, developer advocates demoing agent reliability to prospective buyers.
+
+### Primary value prop
+
+> "Every A2A task now comes with a complete, structured execution record — so you know exactly what your agent did, without wiring up a third-party SDK."
+
+### Recommended messaging angle
+
+**Lead with developer productivity / debugging, not observability infrastructure.**
+
+The 2am pager scenario is the most resonant entry point: *"You know the final output. Now you know exactly how it got there."* This speaks directly to the platform engineering persona and lands without requiring them to understand A2A internals.
+
+**Use these phrases in top-level copy:** "execution tracing," "agent observability," "know what your agent did"
+**Avoid leading with:** "tool_trace" as a feature name, "Message.metadata" anywhere in copy, "JSONB" anywhere in copy
+
+### Competitive differentiation
+
+| Competitor | Their approach | Molecule AI advantage |
+|-----------|---------------|----------------------|
+| Langfuse / Helicone / Braintrust | Third-party SDK, separate pipeline, sampling-based | Tool Trace ships inside every A2A response — zero config, no SDK, no pipeline |
+| Datadog / Splunk | Generic LLM observability, requires instrumentation | Molecule-specific layer — captures A2A-level agent behavior (tool call sequences) that generic LLM pipelines miss or flatten |
+| OpenTelemetry | Standard for distributed tracing, requires agent instrumentation | Platform-native, no instrumentation needed; captures at A2A layer not model-call layer |
+| Hermes (Molecule native) | Traces individual model calls | Tool Trace traces *agent behavior* — tool call sequences, not model tokens. Complementary, not competitive. |
+
+**Counter-framing for sellers:**
+> "Langfuse and Helicone are great for cross-platform, multi-model observability. Tool Trace is your Molecule-specific layer inside your existing stack — and it ships with every response, no instrumentation required."
+
+### HN/Reddit framing
+
+**Do:** Lead with developer experience. *"Tool Trace ships today in Molecule AI. Every agent turn now includes a structured record of every tool called — inputs, output previews, run_id-paired for parallel calls."* Be honest: beta feature.
+
+**Do NOT:** Claim this is GA. Don't say "generally available" or "production-ready by default." Say "now in beta" or "shipping today."
+
+---
+
+## PART 2 — PLATFORM INSTRUCTIONS
+
+### What it is
+
+Platform Instructions is a governance layer that prepends workspace-scoped rules to the system prompt at workspace startup. Rules take effect *before* the first agent turn — shaping what the agent is instructed to do from the start, not filtering outputs after the fact.
+
+Two scoping levels:
+- **Global** — applied to every workspace in the org. One rule, enforced everywhere.
+- **Workspace** — applied to a specific workspace only. Fine-grained control without global impact.
+
+Policy updates take effect at the next workspace restart. No code change, no application redeploy, no agent restart required.
+
+### Who it's for
+
+**Primary:** Enterprise IT, Security/Compliance leads, CISO office.
+
+**Secondary:** Platform Engineering leads who need to enforce org-wide guardrails without touching agent code.
+
+### Primary value prop
+
+> "Governance before the first token is generated — not after an incident."
+
+### Recommended messaging angle
+
+**Lead with pre-execution governance and compliance, not admin control.**
+
+The core contrast that resonates with enterprise buyers: most governance tools are *reactive* (filter outputs after the agent has already acted). Platform Instructions is *proactive* (shapes behavior before the first turn). Frame it as the difference between a guard on the exit door and a guard at the entrance.
+
+**Use these phrases:** "governance before agents run," "pre-execution guardrails," "policy without a deployment," "shape agent behavior at the system prompt level"
+
+**Avoid leading with:** "admin control," "workspace policies," or anything that sounds like IT bureaucracy. The value is speed and safety, not restriction.
+
+### Competitive differentiation
+
+| Competitor | Their approach | Molecule AI advantage |
+|-----------|---------------|----------------------|
+| OPA / Sentinel (policy-as-code) | Runtime resource access enforcement | Platform Instructions fires earlier in the chain (pre-execution vs. during-execution). Complementary, not competitive. |
+| Output filtering (most platforms) | Post-hoc filtering of agent outputs | Platform Instructions shapes behavior *before* the model generates anything. Proactive vs. reactive. |
+| Custom system prompt injection | Requires code changes per workspace | Platform Instructions is workspace-scoped config — no code, no redeploy. |
+| CrewAI / LangGraph | No equivalent feature | First-mover at the agent orchestration layer. |
+
+**Counter-framing for sellers:**
+> "Policy engines like OPA and Sentinel are strong for runtime resource access. Platform Instructions works upstream — at the system prompt level, before the first token is generated. Use both together."
+
+### HN/Reddit framing
+
+**Do:** Frame as "the missing governance layer for production agents." Emphasize that governance that only works after the fact is governance that failed.
+
+**Do NOT:** Overclaim compliance certifications. Do not compare directly to OPA/Sentinel — say "complements runtime policy engines," not "replaces them." Do not publish specific policy examples until PM confirms which are GA-ready.
+
+---
+
+## PART 3 — COMBINED NARRATIVE
+
+### The Phase 34 headline story
+
+**"Molecule agents come with built-in execution tracing and pre-execution governance — nothing to bolt on."**
+
+These two features form a coherent governance + observability stack:
+
+- **Platform Instructions** → governs what agents do *before* they run (proactive)
+- **Tool Trace** → records what agents *actually did* after they run (reactive)
+
+Together: *"governance before, observability after. Nothing leaves production unaccounted for."*
+
+This is the Phase 34 headline theme. Use it in blog post intros, social copy, and launch announcement.
+
+### Feature relationship diagram
+
+```
+Platform Instructions          Tool Trace
+(pre-execution)               (post-execution)
+      ↓                              ↓
+Shapes agent behavior    ←  Records agent behavior
+before first turn             after every task
+
+Combined: proactive governance + complete execution record
+```
+
+### Phase 34 cross-sell (for sellers)
+
+> "Phase 30 gave you per-workspace auth tokens (`mol_ws_*`). Phase 34 gives you platform-native observability (`Tool Trace`) and governance (`Platform Instructions`). Together: enterprise-ready from day one."
+
+### Partner API Keys linkage
+
+Issue #1831 does NOT cover Partner API Keys (that's Issue #1831's sister issue). But for combined Phase 34 copy, the full stack story is:
+
+1. **Partner API Keys** → provision + manage orgs via API
+2. **Platform Instructions** → govern agent behavior per tenant/org
+3. **Tool Trace** → full observability per tenant/org
+4. **SaaS Federation v2** → multi-tenant isolation
+
+*Reference: "an early design partner" — no real partner name in copy until PM confirms.*
+
+---
+
+## PART 4 — COPY GUARDRAILS
+
+### Required disclaimers
+
+| Feature | Required disclaimer | When to use |
+|---------|-------------------|-------------|
+| Tool Trace | "Now in beta" | All external copy (HN, Reddit, LinkedIn, blog) |
+| Platform Instructions | "Now in beta" | All external copy |
+| Both | Do NOT say "GA," "generally available," or "production-ready by default" | Hard stop — do not use in any copy |
+
+### Prohibited framings — DO NOT USE
+
+| Prohibited framing | Why | Replace with |
+|-------------------|-----|-------------|
+| "Tool Trace is like Langfuse" | Not equivalent — different layer, different mechanism | "Built-in execution tracing, no SDK required" |
+| "Platform Instructions replaces OPA/Sentinel" | Complementary, not competitive | "Works alongside runtime policy engines" |
+| Any specific policy rule examples as GA-ready | PM not confirmed | "Enforce any workspace-level behavior rule at the system prompt level" |
+| "Acme Corp" in published copy | Placeholder only | "an early design partner" |
+| Rate limits or pricing for Partner API Keys | Not confirmed by PM | "Invite-only private access — apply at [partner contact]" |
+| `mol_pk_test_*` sandbox keys | Post-GA only | Do not mention |
+| "GA" or "generally available" for any Phase 34 feature | Not confirmed | "Now in beta," "shipping today," "now available" |
+| "Message.metadata" or "JSONB" | Internal implementation detail | Never in external copy |
+
+### Required framing — MUST USE
+
+- Lead with the developer experience, not the feature name (say "execution tracing" not "Tool Trace" in headlines)
+- Lead with "governance before agents run" not "admin control" for Platform Instructions
+- Partner API Keys: lead with CI/CD ephemeral org lifecycle story as the hook (per PM copy guardrail)
+- All Phase 34 external copy: include Phase 30 cross-link ("built on Phase 30 workspace isolation")
+
+### Label guidance
+
+| Feature | Label | Safe alternatives |
+|---------|-------|------------------|
+| Tool Trace | **BETA** | "now in beta," "shipping today," "in early access" |
+| Platform Instructions | **BETA** | "now in beta," "shipping today," "in early access" |
+| Partner API Keys | **INVITE-ONLY BETA** | "invite-only private access," "apply for early access" |
+| SaaS Federation v2 | **BETA** (pending PM confirmation) | "now in beta" — do not publish until PM confirms scope and label |
+
+---
+
+## PART 5 — ASSET CHECKLIST
+
+| Asset | Owner | Status | Notes |
+|-------|-------|--------|-------|
+| Issue #1831 PMM positioning brief (this doc) | PMM | ✅ READY | Cleared for Content Marketer + Social Media Brand use |
+| Tool Trace blog post (`2026-04-23-tool-trace-observability/`) | Content Marketer | ✅ Staged | "AI Agent Observability Without the Overhead" — aligned with brief |
+| Platform Instructions blog post (`2026-04-23-platform-instructions-governance/`) | Content Marketer | ✅ Staged | "Govern Your AI Fleet at the System Prompt Level" — aligned with brief |
+| Phase 34 combined blog (`2026-04-23-tool-trace-platform-instructions/`) | Content Marketer | ✅ Staged | PR #1799 |
+| Social copy (X + LinkedIn) | Social Media Brand | ⏳ Awaiting brief | This doc is the brief — ready to execute |
+| Issue #1831 close | PMM | ✅ Ready to close | Positioning locked; blog posts verified aligned |
+
+---
+
+*Status: READY — gate cleared. Content Marketer and Social Media Brand may proceed.*
+*PMM: close Issue #1831 after confirming Content Marketer has received this brief.*