# Open Digital Product Factory

**The platform that builds itself.** An open-source, AI-native operating platform for small businesses and product teams under human governance. A DPF install starts from a market archetype, gives the business a customer portal and internal workspace in its own vocabulary, and puts purposed AI coworkers at the center of daily work. Single-org install on your hardware; opt-in cross-install contribution through the Hive Mind.

> **For potential users and customers, start at [opendigitalproductfactory.com](https://opendigitalproductfactory.com)** — the canonical product tour with capability inventory, archetypes, coworker workforce, maturity surface, and standards conformance.
>
> **This README is for people working with the project source** — contributors, integrators, and anyone running the install scripts or modifying the codebase.

---

## Product posture

DPF's user story is now archetype-led rather than module-led:

- Pick the business type first: HVAC, clinic, retail, nonprofit, HOA, professional services, software platform, and other small-business categories.
- The selected archetype shapes the customer portal, internal workspace vocabulary, worker home, marketing posture, and feature-contribution applicability.
- AI coworkers are the primary interaction surface. They are purposed by role and route, but every side effect still goes through role checks, agent grants, approval gates, and audit logs.
- WWMD is the trust-building autonomy path: coworkers can consult the founder-kernel wiki and principle vectors for ambiguous decisions, then return a confidence-scored recommendation, arbitration, escalation, or deferral with sources and an audit ledger.
- Voice is an optional coworker modality: speech-to-text for input, text-to-speech for narrated decision/profile output where consent and provider setup allow it.
- Build Studio is the governed self-development surface, but it is still being hardened. Use it honestly: ready for guided platform work and evidence capture, not a claim that every complex source change is fully autonomous today.

User-facing narrative lives in [Market Archetypes And Coworkers](docs/user-guide/market-archetypes.md), with proof personas under [docs/personas/](docs/personas/).

---

## AI Agent Standards

This repository hosts a draft standards family for trustworthy AI-agent operation and identity. DPF is the first implementation and conformance case.

- [Trusted AI Kernel (TAK)](docs/architecture/trusted-ai-kernel.md) — runtime governance, authority mediation, HITL, delegation, audit, provider backpressure, queueing, failover
- [Global AI Agent Identification and Governance (GAID)](docs/architecture/GAID.md) — identity, issuer / accreditation, badging, assurance, authorization classes, chain-of-custody
- [Trusted AI Agent Governance White Paper](docs/architecture/2026-04-18-trusted-ai-agent-governance-white-paper.md) — market, policy, and implementation case
- [DPF Standards Conformance Assessment](docs/architecture/agent-standards-dpf-conformance.md) — how the platform maps to the proposed controls today

Publication outputs are generated from the Markdown sources of truth:

```bash
pnpm docs:tak
node docs/architecture/generate-gaid-docx.mjs
node docs/architecture/generate-agent-standards-white-paper-docx.mjs
```

---

## Quick install

These commands assume a fresh machine with no DPF repo yet. If you've already cloned the repo (contributors), skip to **Step 2** from inside the repo.

### Windows 10 / 11 — **GA**

The Windows installer is a self-contained PowerShell script that clones the repo for you.

```powershell
# Step 1 — download the installer (run from any directory)
iwr -UseBasicParsing https://raw.githubusercontent.com/OpenDigitalProductFactory/opendigitalproductfactory/main/install-dpf.ps1 -OutFile install-dpf.ps1

# Step 2 - run it (prompts for install directory; may suggest a non-C drive)
powershell -ExecutionPolicy Bypass -File install-dpf.ps1
```

### macOS Apple Silicon — Early access · [full guide](docs/install/macos.md)

The Unix installer sources helper libraries from inside the repo, so you must clone first.

```bash
# Step 1 — clone the repo and enter it
git clone https://github.com/OpenDigitalProductFactory/opendigitalproductfactory.git
cd opendigitalproductfactory

# Step 2 — run the installer
bash install-dpf.sh
```

### Linux (native Docker) — Early access · [full guide](docs/install/linux.md)

```bash
git clone https://github.com/OpenDigitalProductFactory/opendigitalproductfactory.git
cd opendigitalproductfactory
bash install-dpf.sh
```

### Cloud Single VM (AWS / GCP / Azure) — Early access · pilots wanted · [full guide](docs/install/cloud-single-vm.md)

Inside the VM:

```bash
git clone https://github.com/OpenDigitalProductFactory/opendigitalproductfactory.git
cd opendigitalproductfactory
bash install-dpf.sh --headless --release
```

Terraform modules for the cloud-VM path live under [`infra/terraform/single-vm/{aws,gcp,azure}/`](infra/terraform/single-vm/).

The installer asks one question — **Ready to go** (pre-built images; Build Studio is the governed development surface) or **Customizable** (full source clone; Build Studio and a local IDE share the same workspace). Both modes include the full platform; the difference is whether direct IDE access is part of the supported workflow. For serious source changes while Build Studio continues hardening, use Customizable mode. Login credentials are saved to `.env` / `.admin-credentials` at the end of installation.

If you hit a wall — happy-path success stories and "the installer hit a wall at step X" failures are equally useful — open an issue using the [Install verification report template](.github/ISSUE_TEMPLATE/install_verification.md) and attach the bundle produced by `bash install-dpf.sh doctor`.

---

## Working on the source

If you want to contribute to the codebase rather than just run it:

- [Developer Setup](docs/user-guide/getting-started/developer-setup.md) — native `pnpm` + Docker sidecars, IDE debugging, hot reload.
- [Dev Container Setup](docs/user-guide/getting-started/dev-container.md) — fully containerized; only Docker Desktop and VS Code required.
- [Development Workspace](docs/user-guide/development-workspace.md) — how Build Studio, VS Code, policy states, and validation environments fit together.

### Shared workspace model

Self-developing installs use one shared workspace per install:

- Build Studio always works from that workspace.
- In customizable installs, VS Code works from the same workspace.
- Production promotion is governed through the portal.
- Contribution policy (`fork_only` / `selective` / `contribute_all`) is configured later in the portal.

### Source isolation vs. runtime isolation

Worktrees created by `scripts/new-dev-worktree.sh` give you **source-control** isolation — your branch, your working tree, your commits — so concurrent sessions and the self-upgrade loop don't reset your work. They are **not** a second runtime.

For each change:

- Edit and commit from the worktree.
- Cheap source-local checks (targeted Vitest, `pnpm typecheck` on the changed package) can run in the worktree if its deps resolve cleanly.
- For anything that exercises the live platform — portal routes, server actions, MCP tools, DB-bound behavior, Build Studio flows — verify against the canonical install at the root clone (or a leased shared nonprod environment), and capture that evidence in the PR.
- If the worktree can't run a build/test because pnpm/corepack isn't on PATH, workspace symlinks point outside the worktree, the Prisma client is missing, or Turbopack rejects a cross-workspace symlink — that's a harness limitation, not a product defect. Route the verification through the **shared local-CI convergence sandbox** (one runtime every worktree leases sequentially via `local-integration-ci`); per-worktree runtimes don't scale at DPF's expected 1k–10k concurrent worktrees.

Full rule: [AGENTS.md §5](AGENTS.md) and [`worktree-is-source-control-not-runtime`](docs/founder-kernel/wiki/principles/worktree-is-source-control-not-runtime.md). The `Quick dev commands` below assume you're either in the root install or a worktree whose dep graph already resolves — they are not a claim that every worktree is a standalone runtime.

### Quick dev commands

| Task | Command |
|------|---------|
| Install dependencies | `pnpm install` |
| Start the dev server | `pnpm dev` |
| Typecheck | `pnpm typecheck` |
| Run tests | `pnpm test` (Vitest) |
| Generate TAK Word doc | `pnpm docs:tak` |
| Diagnostic bundle | `bash install-dpf.sh doctor` |
| Verify the install | `bash scripts/verify-install-edge.sh` |
| Stop / start the running stack | `bash dpf-stop.sh` · `bash dpf-start.sh` |

Pre-commit hooks run typecheck. **Run `pnpm test` locally before pushing** — CI runs the full Vitest suite and breaks for everyone if a test regresses.

---

## Repo layout

```
apps/
  web/                 Next.js portal — the platform surface
  mobile/              React Native 0.83 / Expo SDK 55 / React 19.2 companion app

packages/
  db/                  Prisma schema, seeds, migrations, model profiles
  api-client/          Typed client for the portal API
  validators/          Shared Zod validators (incl. edge event envelope)
  types/               Cross-package type-only exports
  finance-templates/   AI provider supplier contract templates
  storefront-templates/  Storefront archetype scaffolds
  integration-shared/  Shared adapter contracts

services/
  edge-node/           Linux container Edge Node runtime
  edge-node-go/        Mode 4 native Edge Node binary (Windows / macOS / embedded)
  adp/                 ADP payroll connector (early)
  browser-use/         Headless browser MCP service
  integration-test-harness/  E2E test harness

infra/
  terraform/single-vm/{aws,gcp,azure}/   Cloud Single-VM modules

docs/
  index.html                            Public homepage (opendigitalproductfactory.com)
  README.md                             Documentation index
  user-guide/                           Operator-facing pages, also bundled into in-app help
  install/                              Per-platform install runbooks
  architecture/                         TAK, GAID, white paper, conformance, diagrams
  superpowers/specs/                    Dated design specs (the "why" record)
  superpowers/plans/                    Dated implementation plans (the "how" record)
  founder-kernel/wiki/principles/       Tiered platform principles (retrievable via wiki_query MCP)

scripts/             Install, lifecycle, build, backup, hardware detection, verification
.github/             Workflows, issue templates, DCO config
```

Three buckets matter when filing new contributor material:

- **`docs/superpowers/specs/`** — design rationale, dated, append-only history of decisions
- **`docs/superpowers/plans/`** — implementation plans, also dated, tracked through to ship
- **`docs/user-guide/`** — operator-facing pages, bundled into the portal's in-app help

Specs and plans are historical context; user-guide pages are onboarding material.

---

## Architecture & deployment specs

The deployment architecture keeps Windows, macOS, native Linux, customer-cloud, and TAPPaaS aligned to the same canonical contracts while each target carries its own maturity level:

- [Deployment Contracts](docs/superpowers/specs/2026-05-09-deployment-contracts.md) — 10 canonical contracts every deployment target wraps (release artifacts, runtime config, lifecycle, identity, edge, build execution, observability, secrets, LLM / agent routing, client / API surfaces)
- [Cloud Deployment Design](docs/superpowers/specs/2026-05-09-cloud-deployment-design.md) — substrates (Single VM, Managed container service, Managed Kubernetes) and packaging targets
- [DPF Edge Node](docs/superpowers/specs/2026-05-09-dpf-edge-node-design.md) — host-resident trust + connectivity for discovery, MCP / A2A gateway, identity brokering
- [Edge Node Deployment Matrix](docs/superpowers/specs/2026-05-20-edge-node-deployment-matrix.md) — Mode 1 container vs. Mode 4 native binary per host substrate, with the verified-2026-05-20 Docker Desktop finding
- [Build Execution Provider](docs/superpowers/specs/2026-05-09-build-execution-provider-design.md) — sandbox lifecycle abstraction so Build Studio runs on substrates beyond local Docker
- [Mac / Linux Installer-Parity Roadmap](docs/superpowers/plans/2026-05-09-macos-linux-native-support.md) — 10-phase implementation plan for native macOS (Apple Silicon) + native Linux installs

For runtime topology — container layout, hardware tiers, Docker Compose breakdown, monitoring stack — see [`docs/architecture/platform-overview.md`](docs/architecture/platform-overview.md).

---

## Contributing

### The Hive Mind model

1. Install and run your own instance.
2. Add capabilities for your context.
3. Share back what's useful to others.

Every extension — a new role, a new route, a new agent skill — follows the same pattern. No special access needed. Fork, build, contribute.

### The contributor rulebook

[**AGENTS.md**](AGENTS.md) is the canonical operating contract for any AI agent working in this codebase, and it doubles as the durable operating rules for human contributors. Tool-specific files (`CLAUDE.md`, `.cursor/rules/`, `.clinerules/`, `.github/copilot-instructions.md`, `CONVENTIONS.md`, `.continue/rules/`) are pointers to it — do not duplicate rules into them.

Durable governance also lives as tiered principles under [`docs/founder-kernel/wiki/principles/`](docs/founder-kernel/wiki/principles/), retrievable at runtime via the `wiki_query` MCP tool.

### Branch model + PR workflow

- Topic branches off `origin/main` — short-lived, one PR per branch
- All changes land via PR; `main` is the release branch, force-push protected
- **DCO sign-off required** on every commit (`git commit -s`)
- For **concurrent sessions**: each runs in its own `git worktree`; use `git commit --only <paths>` with positional arguments so a parallel session's staged files do not sweep into your commit
- Never `--no-verify`, never `--no-gpg-sign`, never amend across sessions

### CI gates contributors will see

| Gate | What it does | Notes |
|------|--------------|-------|
| **DCO** | Confirms every commit carries `Signed-off-by:` | Required. Use `git commit -s`. |
| **signoff** | App-tier sign-off check | Skipped if no concerns flagged. |
| **Typecheck** | `pnpm typecheck` against the merged tree | Pre-commit hook only runs this; CI is the canonical run. |
| **Unit Tests** | Full Vitest suite | Run locally before pushing. |
| **Production Build** | `next build` | Catches Turbopack / NFT cascade regressions. |
| **Analyze (actions / go / javascript-typescript / python)** | CodeQL across the multi-language tree | The Go agent under `services/edge-node-go/` is in scope. |
| **Routing Invariants Audit** | Re-runs seed + invariant guards against the PR's merge-base | Failure typically means a seed contract drifted; rebase onto current `main` if a fix has since landed. |
| **Routing Tier Contract** | Verifies `ModelTierPolicy` cost-tier → model bindings are consistent | Touches anything under `packages/db/data/`? Expect this gate. |
| **Stall Detection Write Guard** | Asserts stall-detection invariants for Build Studio recovery | Touches `apps/web/lib/build-studio/`? Expect this gate. |
| **Dockerfile Node Version** | Asserts the Node version in `Dockerfile*` matches the workspace | Bumping Node? Update all three Dockerfiles. |

### Code standards

- TypeScript strict mode (`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`)
- New features need Vitest tests
- Follow existing patterns (server actions, React cache, auth gates)
- Stay current on dependencies — bump patch / minor proactively; capture blocked majors as tracked work

Longer-form contributor guidance — full branch model, PR checklist, local verification workflow, the cross-session etiquette — lives in [**CONTRIBUTING.md**](CONTRIBUTING.md).

---

## Docs index

- [docs/README.md](docs/README.md) — documentation index
- [docs/user-guide/](docs/user-guide/) — operator-facing guides, bundled into the portal's in-app help
- [docs/user-guide/market-archetypes.md](docs/user-guide/market-archetypes.md) — archetype-led user narrative and coworker positioning
- [docs/personas/](docs/personas/) — persona proof library for archetype-led marketing and dogfood testing
- [docs/install/](docs/install/) — per-platform install runbooks
- [docs/architecture/](docs/architecture/) — runtime, deployment, standards, governance
- [docs/superpowers/specs/](docs/superpowers/specs/) — dated design specs (the "why" record)
- [docs/superpowers/plans/](docs/superpowers/plans/) — dated implementation plans

---

## License

Licensed under the [Apache License, Version 2.0](LICENSE).

Contributions are accepted under the [Developer Certificate of Origin (DCO)](https://developercertificate.org/). By submitting a pull request, you certify that your contribution is your original work and you grant an irrevocable license under the project's Apache-2.0 license.

Required attributions for bundled open-source dependencies are listed in [NOTICE](NOTICE). Credit to the standards bodies, frameworks, and authors whose ideas shaped DPF is in [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md).
