docs: refresh README roadmap and four pillars (#9922)

## Thinking Path

> - Paperclip is the open source control plane people use to organize
and govern companies of AI agents
> - The README is the project’s front door, while `ROADMAP.md` is the
detailed statement of shipped and planned product direction
> - The existing README roadmap had fallen behind capabilities that are
already available and did not explain the product’s organizing model
> - That drift made current features look unfinished and left the
relationship between tasks, organization, training, and infrastructure
implicit
> - This pull request synchronizes the roadmap preview with the detailed
roadmap and introduces the four-pillar product framing
> - The benefit is a more accurate, coherent first impression for users
and contributors, with theme-aware visuals that render correctly on
GitHub

## Linked Issues or Issue Description

- **Subsystem affected:** Documentation (`README.md`, `ROADMAP.md`, and
documentation assets); no runtime subsystem changes.
- **Problem or motivation:** The README roadmap understated shipped
capabilities, the detailed roadmap had corresponding stale statuses, and
the README did not clearly explain the four product pillars that connect
Paperclip’s task, organization, training, and infrastructure surfaces.
- **Proposed solution:** Refresh both roadmap views from one ordered
list, add the four-pillars section and light/dark graphic, and keep
future capabilities explicitly marked as planned or partial.
- **Alternatives considered:** Updating only `ROADMAP.md` would leave
the project’s front page stale; updating only the README would create a
second source of truth; a single non-theme-aware image would be less
legible for half of GitHub’s color schemes.
- **Roadmap alignment:** This change directly updates `ROADMAP.md` and
its README preview rather than introducing an unplanned runtime feature.
- **Additional context:** Searched open pull requests for related README
roadmap/four-pillars work and found no duplicate.

## What Changed

- Added a **The four pillars** section covering Agentic Task Manager,
Org Chart for Agents, Agent Employee Training, and Agentic OS, with a
theme-aware `<picture>` graphic.
- Flipped four roadmap entries from ⚪ to ✅: Cloud / Sandbox agents,
Artifacts & Work Products, Deep Planning, and Enforced Outcomes.
- Added shipped ✅ entries for MCP Tool Gateway & Apps, per-agent Secrets
Manager access, activity logging and action attribution, self-healing
recovery, and agent evals/feedback; expanded the skills entry to include
Skill Studio and Skills Store.
- Added planned ⚪ entries for Bring-your-own-ticket-system and Connected
Apps, resolving the README FAQ inconsistency around external ticket
systems.
- Moved Cloud deployments to 🟡 and documented the shipped multi-tenant
isolation, local-to-cloud sync, and cloud-managed bootstrap scope.
- Synchronized the README preview and `ROADMAP.md` ordering/statuses: 18
✅, 9 ⚪, and 1 🟡 entry.

## Verification

- `git diff --check origin/master...HEAD`
- Focused Node consistency check confirms README and `ROADMAP.md` have
the same 28 ordered entries/statuses and expected 18 ✅ / 9 ⚪ / 1 🟡
counts.
- `file doc/assets/four-pillars-light.png
doc/assets/four-pillars-dark.png` confirms both assets are valid
3840×2160 RGB PNGs.
- Visual QA rendered the README through GitHub’s GFM API in Chromium at
GitHub content width under both light and dark `prefers-color-scheme`
modes; the correct graphic swapped per theme, all links resolved, the
section placement/table were correct, and `ROADMAP.md` matched the
README preview.

### Visual Evidence

**Light theme**

![Rendered README four-pillars section in light
theme](https://raw.githubusercontent.com/paperclipai/paperclip/pr-evidence-9922/pr-evidence/9922/light-pillars.png)

**Dark theme**

![Rendered README four-pillars section in dark
theme](https://raw.githubusercontent.com/paperclipai/paperclip/pr-evidence-9922/pr-evidence/9922/dark-pillars.png)
- Prettier was not run because this repository does not expose a
configured `prettier` binary; markdown whitespace was checked with `git
diff --check` and the rendered QA above.

## Risks

- Low risk: documentation and image assets only; no application code,
API contract, schema, dependencies, lockfile, or workflow changes.
- Roadmap status wording can become stale as product work evolves, so
future shipped capabilities should update both the README preview and
`ROADMAP.md` together.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex, exact model ID `gpt-5.6-sol`, with reasoning,
terminal/tool use, GitHub API access, and Paperclip control-plane
integration. The model context-window size was not exposed by this
execution environment.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

README.md

@@ -76,6 +76,25 @@ It looks like a task manager. Under the hood: org charts, budgets, governance, g
 
 <br/>
 
+## The four pillars
+
+Four things have to work for an organization of AI agents to actually produce: the tasks, the org, the training, and the infrastructure. Paperclip is built around exactly those four pillars.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/paperclipai/paperclip/1ec33ffd8b597f7e36aac3e2fbb4665b8c42dc3c/doc/assets/four-pillars-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/paperclipai/paperclip/1ec33ffd8b597f7e36aac3e2fbb4665b8c42dc3c/doc/assets/four-pillars-light.png">
+  <img src="https://raw.githubusercontent.com/paperclipai/paperclip/1ec33ffd8b597f7e36aac3e2fbb4665b8c42dc3c/doc/assets/four-pillars-light.png" alt="The four pillars of Paperclip">
+</picture>
+
+| Pillar | Built for | What it covers |
+| --- | --- | --- |
+| **Agentic Task Manager** — Declare intent. Agents work. You verify the output. | Everyone, daily | Tasks, approvals & review gates · proactive agent coworkers · auditable routines & workflows · verify from diffs, screenshots & tests |
+| **Org Chart for Agents** — Roles, permissions & boundaries for humans and agents. | Managers | Mixed human + agent org chart · responsibilities, delegation, specialization · governance: who can do what · scoped secrets & company boundaries |
+| **Agent Employee Training** — Design, train & evaluate your AI employees. | Enablers | Skill Studio & shared org-wide skills · evals & saved test runs · active learning loops & quality metrics · performance reviews for agents |
+| **Agentic OS** — The infrastructure that makes the work run. | IT & platform | Cross-provider runtime: any model, any agent · sandboxing, integrations & MCP servers · SSO, GRC, RBAC & cost controls · data privacy, internal trace collection, compounding data value |
+
+<br/>
+
 ## Features
 
 <table>
@@ -375,23 +394,30 @@ See [doc/DEVELOPING.md](doc/DEVELOPING.md) for the full development guide.
 - ✅ Get OpenClaw / claw-style agent employees
 - ✅ companies.sh - import and export entire organizations
 - ✅ Easy AGENTS.md configurations
-- ✅ Skills Manager
+- ✅ Skills Manager, Skill Studio & Skills Store
 - ✅ Scheduled Routines
 - ✅ Better Budgeting
 - ✅ Agent Reviews and Approvals
 - ✅ Multiple Human Users
-- ⚪ Cloud / Sandbox agents (e.g. Cursor / e2b / Novita agents)
-- ⚪ Artifacts & Work Products
+- ✅ Cloud / Sandbox agents (e2b, Cloudflare, Daytona, Modal, Novita, self-hosted Kubernetes)
+- ✅ Artifacts & Work Products
+- ✅ Deep Planning (planning mode, revisioned plans, plan approvals)
+- ✅ Enforced Outcomes (watchdogs, recovery actions, review gates)
+- ✅ MCP Tool Gateway & Apps (governed tool access)
+- ✅ Secrets Manager with per-agent access
+- ✅ Activity log & action attribution
+- ✅ Self-healing runs & automatic recovery
+- ✅ Agent evals & feedback
 - ⚪ Memory / Knowledge
-- ⚪ Enforced Outcomes
 - ⚪ MAXIMIZER MODE
-- ⚪ Deep Planning
 - ⚪ Work Queues
 - ⚪ Self-Organization
 - ⚪ Automatic Organizational Learning
 - ⚪ CEO Chat
-- ⚪ Cloud deployments
+- 🟡 Cloud deployments (multi-tenant isolation & local→cloud sync shipped)
 - ⚪ Desktop App
+- ⚪ Bring-your-own-ticket-system (Asana / Linear / Jira as on-ramps)
+- ⚪ Connected Apps (one-click integrations, e.g. Vercel)
 
 This is the short roadmap preview. See the full roadmap in [ROADMAP.md](ROADMAP.md).
 

ROADMAP.md

@@ -28,9 +28,9 @@ Reusable companies matter. Import/export is the foundation for moving org struct
 
 Agent setup should feel repo-native and legible. Simple `AGENTS.md`-style configuration lowers the barrier to getting an agent team running and makes it easier for contributors to understand how a company is wired together.
 
-### ✅ Skills Manager
+### ✅ Skills Manager, Skill Studio & Skills Store
 
-Agents need a practical way to discover, install, and use skills without every setup becoming bespoke. The skills layer is part of making Paperclip companies more reusable and easier to operate.
+Agents need a practical way to discover, install, create, test, and share skills without every setup becoming bespoke. Skills Manager, Skill Studio, and the Skills Store make the skills layer reusable across an organization and easier to operate.
 
 ### ✅ Scheduled Routines
 
@@ -48,30 +48,50 @@ Paperclip should support explicit review and approval stages as first-class work
 
 Paperclip needs a clearer path from solo operator to real human teams. That means shared board access, safer collaboration, and a better model for several humans supervising the same autonomous company.
 
-### ⚪ Cloud / Sandbox agents (e.g. Cursor / e2b / Novita agents)
+### ✅ Cloud / Sandbox agents (e2b, Cloudflare, Daytona, Modal, Novita, self-hosted Kubernetes)
 
 We want agents to run in more remote and sandboxed environments while preserving the same Paperclip control-plane model. This makes the system safer, more flexible, and more useful outside a single trusted local machine.
 
-### ⚪ Artifacts & Work Products
+### ✅ Artifacts & Work Products
 
 Paperclip should make outputs first-class. That means generated artifacts, previews, deployable outputs, and the handoff from "agent did work" to "here is the result" should become more visible and easier to operate.
 
+### ✅ Deep Planning (planning mode, revisioned plans, plan approvals)
+
+Some work needs more than a task description before execution starts. Deeper planning means a dedicated planning mode, revisioned plans, and explicit plan approvals for strategy-heavy work before agents begin execution.
+
+### ✅ Enforced Outcomes (watchdogs, recovery actions, review gates)
+
+Paperclip should get stricter about what counts as finished work. Watchdogs, recovery actions, and review gates keep execution moving toward clear outcomes like merged code, published artifacts, shipped docs, or explicit decisions instead of vague status updates.
+
+### ✅ MCP Tool Gateway & Apps (governed tool access)
+
+MCP tools and apps should be available through a governed gateway instead of unmanaged direct access. Paperclip can apply company boundaries, approval gates, and activity attribution while giving agents the tools they need.
+
+### ✅ Secrets Manager with per-agent access
+
+Secrets need to be centrally managed without giving every agent every credential. Per-agent access, scoped bindings, and audited resolution keep sensitive integrations usable while preserving least privilege.
+
+### ✅ Activity log & action attribution
+
+Operators need a durable record of what changed and who initiated it. Activity history and clear action attribution make human, agent, and system actions inspectable across the control plane.
+
+### ✅ Self-healing runs & automatic recovery
+
+Agent work should recover from routine failures without waiting for a human to notice every stalled run. Recovery policies can retry safe work, route failures, and keep the issue lifecycle aligned with what actually happened.
+
+### ✅ Agent evals & feedback
+
+Agent performance should be measurable over time, not judged only from anecdotes. Evals, saved results, and structured feedback create a loop for improving skills, prompts, models, and employee quality.
+
 ### ⚪ Memory / Knowledge
 
 We want a stronger memory and knowledge surface for companies, agents, and projects. That includes durable memory, better recall of prior decisions and context, and a clearer path for knowledge-style capabilities without turning Paperclip into a generic chat app.
 
-### ⚪ Enforced Outcomes
-
-Paperclip should get stricter about what counts as finished work. Tasks, approvals, and execution flows should resolve to clear outcomes like merged code, published artifacts, shipped docs, or explicit decisions instead of stopping at vague status updates.
-
 ### ⚪ MAXIMIZER MODE
 
 This is the direction for higher-autonomy execution: more aggressive delegation, deeper follow-through, and stronger operating loops with clear budgets, visibility, and governance. The point is not hidden autonomy; the point is more output per human supervisor.
 
-### ⚪ Deep Planning
-
-Some work needs more than a task description before execution starts. Deeper planning means stronger issue documents, revisionable plans, and clearer review loops for strategy-heavy work before agents begin execution.
-
 ### ⚪ Work Queues
 
 Paperclip should support queue-style work streams for repeatable inputs like support, triage, review, and backlog intake. That would make it easier to route work continuously without turning every system into a one-off workflow.
@@ -88,10 +108,20 @@ Paperclip should get better at turning completed work into reusable organization
 
 We want a lighter-weight way to talk to leadership agents, but those conversations should still resolve to real work objects like plans, issues, approvals, or decisions. This should improve interaction without changing the core task-and-comments model.
 
-### ⚪ Cloud deployments
+### 🟡 Cloud deployments (multi-tenant isolation & local→cloud sync shipped)
 
 Local-first remains important, but Paperclip also needs a cleaner shared deployment story. Teams should be able to run the same product in hosted or semi-hosted environments without changing the mental model.
 
+Shipped so far: multi-tenant isolation with per-company JWT keys and company-scoped cloud tenants, local→cloud upstream sync, and cloud-managed instance bootstrap.
+
 ### ⚪ Desktop App
 
 A desktop app can make Paperclip feel more accessible and persistent for day-to-day operators. The goal is easier access, better local ergonomics, and a smoother default experience for users who want the control plane always close at hand.
+
+### ⚪ Bring-your-own-ticket-system (Asana / Linear / Jira as on-ramps)
+
+Existing ticket systems should be able to feed work into Paperclip without becoming the agent control plane themselves. Asana, Linear, and Jira can act as familiar on-ramps while Paperclip owns execution, governance, and outcomes.
+
+### ⚪ Connected Apps (one-click integrations, e.g. Vercel)
+
+Common services should connect without bespoke setup for every company. One-click integrations can package credentials, permissions, and useful workflows for apps such as Vercel while keeping access governed and auditable.