# SolidCage — Agentic OS Demo Suite (Full)

> Free tools, open-source repos, and slide decks for building governed AI employees and digital twin factories.
> Built by Filip Szalewicz — Fractional CTO, SolidCage. The methodology is the Operational Intelligence (OI) Lab framework.

---

## Methodology

SolidCage applies the **Agentic OS** pattern: treat an organisation not as a hierarchy of roles, but as an operating system with human and AI agents executing tasks within a governed, auditable stack.

Four lenses drive every decision:
- **PPT (People · Process · Technology)** — who is affected, what process changes, what technology enables it
- **Pareto (80/20)** — focus the 20% of work that delivers 80% of the value
- **30/60/90** — map all recommendations to Immediate / Soon / Later
- **Rate of Improvement (RoI)** — the real KPI is not output, it is whether the output curve is accelerating

The **agent-kernel** is the reusable substrate that encodes these lenses as injectable skills, prompts, and templates. A **digital twin** is a governed AI employee built on this substrate, spec'd from an interview with the principal.

---

## Apps

### SolidCage Apps Hub
URL: https://apps.solidcage.com/
Hub index listing all tools, slide decks, and open-source repositories. Includes a live CLI-style terminal block that renders `apps.json` and shows the agent discovery surface. No login required.

### Digital Twin Factory Demo Portal
URL: https://apps.solidcage.com/twin-portal/
Multi-page portal demonstrating the Digital Twin Factory pattern:
- **Home** — thesis: every leader needs a governed AI double
- **Twin Gallery** — example twins (Fractional CTO, Head of Sales, Chief of Staff, Operations Director)
- **Scorer** — 5-question readiness check for a specific twin use case
- **ROI Simulator** — slider-based cost/benefit model with breakeven and annual savings
- **Architecture** — Mermaid diagram of the full factory stack (agent-kernel → twin spec → factory runtime → HITL queue → audit log)
- **Intake Form** — structured form to start a real twin engagement
- **Control Plane** — animated "running twins" dashboard demo

### Digital Twin Builder
URL: https://apps.solidcage.com/twin-portal/twin-builder/
AI-powered interview wizard that produces a deployable digital twin package in ~10 minutes.

Interview flow (5 topic areas):
1. Identity and role — name, title, org type, elevator pitch
2. Domain expertise — top 2-3 subjects, decisions only they get pulled into
3. Communication style — tone, brevity, formality, structure
4. Decision patterns — recurring frameworks, heuristics, instincts
5. Guardrails — what never to do, what always to escalate, ethical lines

Outputs (downloadable as a ZIP):
- `agent-spec.yaml` — machine-readable twin specification
- `identity.md` — prose narrative of the principal's working style
- `guardrails.md` — explicit policy constraints for the twin
- Skill assignments — curated subset of agent-kernel's 26 skills

API: see `/api/openai/twin-builder/*` endpoints in the OpenAPI spec.

### Agent ROI Generator
URL: https://apps.solidcage.com/agent-roi-generator/
5-step wizard to score an AI use case across 6 dimensions and produce a 30/60/90 action roadmap.

Dimensions scored:
1. Strategic alignment
2. Process complexity
3. Data availability
4. Technical feasibility
5. Change management risk
6. Estimated ROI

Output: printable / PDF-exportable report with score breakdown, narrative, and prioritised 30/60/90 roadmap.

### Agentic Readiness Scorecard
URL: https://apps.solidcage.com/agent-roi-generator/scorecard
12-question self-assessment across 5 dimensions that locates an organisation on the 5-stage agentic readiness curve. Radar chart visualisation. Results can be shared as a link.

5 stages of the agentic curve:
1. Reactive — no structured AI use
2. Assisted — AI supplements human work ad-hoc
3. Orchestrated — AI agents run defined workflows
4. Governed — HITL queues, audit logs, policy constraints
5. Autonomous — agents execute independently within defined envelopes

### Operational Intelligence Tracker
URL: https://apps.solidcage.com/oi-tracker/
Log a metric (any KPI) weekly and visualise whether the improvement curve is accelerating, stable, or tapering. The OI Lab thesis: Rate of Improvement is the only KPI that matters. An accelerating RoI curve means the org is compounding; a tapering curve means the agent / process is hitting a ceiling.

---

## Slide Decks

All decks are long-scroll interactive React pages with present mode (fullscreen, keyboard navigation) and PDF export.

### The Agentic OS Playbook
URL: https://apps.solidcage.com/decks/agentic-os-playbook
How to operate an organisation as an agentic OS. Covers PPT framework, agentic readiness stages, governance patterns, the 30/60/90 implementation timeline, and case examples.

### The ROI of AI Employees
URL: https://apps.solidcage.com/decks/roi-ai-employees
Investor-grade business case for governed AI employees. Covers cost model (FTE equivalent vs. twin cost), risk mitigation via HITL, audit trail value, and decision framework for which roles to twin first.

### Digital Twin Factories
URL: https://apps.solidcage.com/decks/digital-twin-factories
Engineering pattern for building and governing digital twin factories at scale. Covers the factory stack, twin lifecycle (install → register → run → audit), HITL approval queue design, and Supabase schema for the audit log.

---

## API

Base URL: https://apps.solidcage.com/api
Full spec: https://apps.solidcage.com/api/openapi.json (OpenAPI 3.1)
Agent manifest: https://apps.solidcage.com/.well-known/agent.json

### GET /api/healthz
Returns server health status. `{ "status": "ok" }`

### POST /api/openai/twin-builder/chat
SSE-streaming interview chat. Stateless — client sends the full conversation history in each request; server streams the next assistant turn as Server-Sent Events.

Request body:
```json
{
  "messages": [
    { "role": "user", "content": "..." },
    { "role": "assistant", "content": "..." }
  ]
}
```

Response: `text/event-stream` — each event contains a text chunk.

### POST /api/openai/twin-builder/synthesize
Consume a completed interview transcript and produce the twin package.

Request body: same `messages` array as /chat.

Response body:
```json
{
  "agentSpecYaml": "...",
  "identityMd": "...",
  "guardrailsMd": "...",
  "skills": [{ "name": "decision-frameworks", "rationale": "..." }],
  "twinId": "twin_abc123",
  "name": "Filip Szalewicz",
  "owner": "filip@solidcage.com"
}
```

### POST /api/openai/twin-builder/email
Email the twin package + deploy guide to the principal.

Request body:
```json
{
  "to": "principal@example.com",
  "package": { ...TwinBuilderPackage... },
  "subscribe": true
}
```

### POST /api/openai/twin-builder/regenerate
Regenerate one section of the twin package with optional guidance.

Request body:
```json
{
  "section": "agentSpecYaml",
  "messages": [...],
  "currentValue": "...",
  "guidance": "Make the guardrails stricter around financial decisions."
}
```

---

## Open-Source Repos (github.com/fszale)

### agent-kernel
URL: https://github.com/fszale/agent-kernel
Injectable principal-operator layer for any AI project. Contents:
- 26 injectable skills (decision-frameworks, domain-expertise, communication-style, stakeholder-mapping, estimation-and-scoping, code-review, incident-response, hiring-and-interviewing, vendor-evaluation, roadmap-planning, executive-reporting, negotiation, coaching-and-feedback, writing-and-editing, research-and-synthesis, meeting-facilitation, data-interpretation, guardrails-and-ethics, knowledge-curation, delegation-and-handoffs, first-principles-thinking, personal-operating-system, and more)
- 19 structured prompt templates
- 17 reusable document templates (agent-spec, 30-60-90 plan, etc.)
- 9 Mermaid diagrams with embed automation
- 6 GitHub Actions for CI/CD validation

### digital-twin-filip
URL: https://github.com/fszale/digital-twin-filip
Filip Szalewicz's own digital twin. Includes persona, role bindings (Fractional CTO, advisor, builder), decision patterns, communication style, and guardrails. Reference implementation of a complete twin spec.

### agent-factory
URL: https://github.com/fszale/agent-factory
Factory runtime for hosting and governing multiple digital twins. Stack: FastAPI + Supabase + React admin dashboard. Features HITL (human-in-the-loop) approval queue, append-only audit log, thread-based conversations, and twin lifecycle management (install from git → register → run → stop).

### agentic-playbook
URL: https://github.com/fszale/agentic-playbook
Operational Intelligence Lab methodology and playbook. Covers the full agentic-OS pattern, readiness assessment, governance design, and implementation roadmap.

### digital-twin-factory
URL: https://github.com/fszale/digital-twin-factory
Reference architecture and methodology for the Digital Twin Factory Demo Portal. Companion to the live demo at apps.solidcage.com/twin-portal/.

### agent-roi-generator
URL: https://github.com/fszale/agent-roi-generator
Source repository for the Agent ROI Generator and Agentic Readiness Scorecard tools. React + TypeScript + Tailwind + jsPDF.

### operational-intelligence-lab
URL: https://github.com/fszale/operational-intelligence-lab
OI Lab rate-of-improvement methodology, templates, and reference materials for operational intelligence practitioners.

---

## Agent Discovery Surfaces

| Surface | URL |
|---|---|
| LLM-friendly site map | https://apps.solidcage.com/llms.txt |
| LLM-friendly site map (full) | https://apps.solidcage.com/llms-full.txt |
| A2A agent manifest | https://apps.solidcage.com/.well-known/agent.json |
| OpenAPI 3.1 spec | https://apps.solidcage.com/api/openapi.json |
| Machine-readable apps index | https://apps.solidcage.com/apps.json |
| Sitemap | https://apps.solidcage.com/sitemap.xml |

---

## Contact

- Book a session with Filip Szalewicz (Fractional CTO): https://crm.solidcage.com/widget/bookings/filip-szalewicz-fractional-cto-calendar-vfs0lblxh
- Website: https://solidcage.com
- GitHub: https://github.com/fszale