feat: PDF-first runtime scaffold — docd, pdf-secure, pdf-viewer-demo, smoke validation

Makefile

@@ -1,5 +1,31 @@
+.PHONY: validate smoke up down
+
+validate:
+	@echo "==> Validating workspace layout..."
+	@test -d services/docd          || (echo "FAIL: services/docd missing"         && exit 1)
+	@test -d services/pdf-secure    || (echo "FAIL: services/pdf-secure missing"   && exit 1)
+	@test -d apps/pdf-viewer-demo   || (echo "FAIL: apps/pdf-viewer-demo missing"  && exit 1)
+	@test -d content/draft          || (echo "FAIL: content/draft missing"         && exit 1)
+	@test -d content/derived        || (echo "FAIL: content/derived missing"       && exit 1)
+	@test -d content/reports        || (echo "FAIL: content/reports missing"       && exit 1)
+	@test -f services/docd/src/derive.js              || (echo "FAIL: services/docd/src/derive.js missing"              && exit 1)
+	@test -f services/pdf-secure/src/sign-validate.js || (echo "FAIL: services/pdf-secure/src/sign-validate.js missing" && exit 1)
+	@test -f apps/pdf-viewer-demo/src/smoke.js        || (echo "FAIL: apps/pdf-viewer-demo/src/smoke.js missing"        && exit 1)
+	@echo "PASS: validate"
+
+smoke:
+	@echo "==> Running smoke tests..."
+	@echo "--- services/docd ---"
+	node services/docd/src/derive.js
+	@echo "--- services/pdf-secure ---"
+	node services/pdf-secure/src/sign-validate.js
+	@echo "--- apps/pdf-viewer-demo ---"
+	node apps/pdf-viewer-demo/src/smoke.js
+	@echo "PASS: smoke"
+
 up:
-  docker compose -f infra/compose/docker-compose.yml up --build
+	docker compose -f infra/compose/docker-compose.yml up --build
 
 down:
-  docker compose -f infra/compose/docker-compose.yml down -v
+	docker compose -f infra/compose/docker-compose.yml down -v
+

README.md

@@ -2,29 +2,73 @@
 
 Primary product/runtime repository for the SourceOS shell.
 
-## Boundary
+## Repo boundary
 
-- `SourceOS-Linux/sourceos-shell` = product/runtime code
-- `SourceOS-Linux/sourceos-spec` = shared machine-readable contracts
-- `SociOS-Linux/source-os` = Linux realization surfaces
-- `SociOS-Linux/albert` = temporary launcher bridge only
+| Repository | Responsibility |
+|---|---|
+| [`SourceOS-Linux/sourceos-shell`](https://github.com/SourceOS-Linux/sourceos-shell) | Product/runtime code (this repo) |
+| [`SourceOS-Linux/sourceos-spec`](https://github.com/SourceOS-Linux/sourceos-spec) | Shared machine-readable contracts |
+| [`SociOS-Linux/source-os`](https://github.com/SociOS-Linux/source-os) | Linux realization surfaces |
+| `SociOS-Linux/albert` | Temporary launcher bridge only |
 
-## Immediate sequencing
+## PDF-first runtime scope
 
-This repository is the runtime home for the broader shell stack, but the first implementation slice is **PDF-first**.
+This repository is the runtime home for the broader shell stack. The **first implementation slice is PDF-first**.
 
-Initial runtime scope:
-- `services/docd` — derive lane
-- `services/pdf-secure` — sign / validate lane
-- `apps/pdf-viewer-demo` — PDF viewer/demo surface
-- `content/` — draft / derived / reports layout
-- minimal workspace/bootstrap files
+### Services
 
-Explicitly deferred until after the PDF lane is real:
-- notes / graph / gallery / playground surfaces
-- broader shell UX expansion
-- non-PDF publication features beyond what the PDF lane needs
+| Service | Path | Role |
+|---|---|---|
+| `docd` | `services/docd` | Derive lane — draft → derived PDF |
+| `pdf-secure` | `services/pdf-secure` | Sign / validate lane |
 
-## Intent
+### Apps
 
-We keep the repo boundary correct without letting the first implementation slice sprawl beyond the PDF/document/runtime lane.
+| App | Path | Role |
+|---|---|---|
+| `pdf-viewer-demo` | `apps/pdf-viewer-demo` | PDF viewer / demo surface |
+
+### Content layout
+
+| Directory | Purpose |
+|---|---|
+| `content/draft` | Source draft documents |
+| `content/derived` | Derived PDFs produced by `docd` |
+| `content/reports` | Validation reports from `pdf-secure` |
+
+## Commands
+
+```bash
+# Validate workspace layout (no external services needed)
+make validate
+
+# Run smoke tests for each runtime slice
+make smoke
+
+# Docker compose (requires Docker)
+make up
+make down
+```
+
+## Contracts
+
+Machine-readable contracts for all inter-service boundaries live in
+[`SourceOS-Linux/sourceos-spec`](https://github.com/SourceOS-Linux/sourceos-spec).
+Do not define contracts in this repo; reference them from `sourceos-spec`.
+
+## Linux realization
+
+OS-level realization surfaces (packaging, init, system integration) live in
+[`SociOS-Linux/source-os`](https://github.com/SociOS-Linux/source-os).
+
+## Explicitly deferred
+
+The following are out of scope until the PDF lane is real:
+
+- Notes / graph / gallery / playground surfaces
+- Broader shell UX expansion
+- Non-PDF publication features beyond what the PDF lane needs
+
+## Status
+
+All runtime slices are **placeholder scaffolds** — smoke-tested, no external services required.

apps/pdf-viewer-demo/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "pdf-viewer-demo",
+  "private": true,
+  "type": "commonjs",
+  "scripts": {
+    "smoke": "node src/smoke.js"
+  }
+}

apps/pdf-viewer-demo/src/smoke.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// pdf-viewer-demo — smoke placeholder
+// Responsibility: PDF viewer/demo surface
+// Contracts live in SourceOS-Linux/sourceos-spec
+
+'use strict';
+
+console.log('[pdf-viewer-demo] smoke OK — viewer/demo placeholder running');
+console.log('[pdf-viewer-demo] Serves   : apps/pdf-viewer-demo/index.html');
+console.log('[pdf-viewer-demo] Status   : placeholder (no external services required)');
+process.exit(0);

docs/ARCHITECTURE.md

@@ -0,0 +1,66 @@
+# SourceOS Shell Architecture
+
+SourceOS Shell is the product/runtime workspace shell for trusted documents, office workflows, search, provenance, and agent evidence.
+
+It is not a GNOME Shell replacement in v0. GNOME remains the desktop shell, compositor, panel, and windowing environment for the first Linux realization. SourceOS Shell integrates with GNOME through desktop entries, launchers, file actions, reports, and adapters.
+
+## Repository boundary
+
+| Repository | Responsibility |
+|---|---|
+| `SourceOS-Linux/sourceos-shell` | Product/runtime shell code: document services, PDF runtime, office/workspace actions, UI packages, router/adapters. |
+| `SourceOS-Linux/sourceos-spec` | Canonical contracts, schemas, examples, evidence object shapes. |
+| `SociOS-Linux/source-os` | Linux realization: host profiles, GNOME defaults, installer, status/doctor, service wiring. |
+| `SocioProphet/agentplane` and related repos | Agent execution evidence, policy/control integration, operator surfaces. |
+
+## Staged model
+
+### Stage 0: PDF-first runtime
+
+The first executable slice is intentionally small:
+
+- `services/docd` derives document artifacts.
+- `services/pdf-secure` signs and validates artifact placeholders.
+- `apps/pdf-viewer-demo` proves the viewer/demo entry point.
+- `content/draft`, `content/derived`, and `content/reports` define the local artifact layout.
+- `make validate` and `make smoke` prove the scaffold is callable without external services.
+
+This does not claim a full PDF engine.
+
+### Stage 1: Document shell
+
+The document shell adds artifact manifests, validation reports, sidecars, annotation export, provenance ribbons, and publishing/report surfaces.
+
+### Stage 2: Office shell
+
+The office shell adds open/create/search/convert/export/template workflows, with LibreOffice/Collabora-compatible open implementation paths where appropriate.
+
+### Stage 3: Workspace/action shell
+
+The workspace shell adds action routing, shell-web surfaces, local report history, agent output inbox, status/doctor/fix report UI, and search-provider routing.
+
+### Stage 4: GNOME adapter
+
+The GNOME adapter integrates SourceOS Shell with Linux desktops through launchers, desktop entries, file-manager actions, notifications, portals, and the SourceOS workstation profile.
+
+### Stage 5: Optional desktop shell path
+
+A GNOME Shell replacement, compositor adapter, or full SourceOS desktop shell is deferred until the document/runtime shell proves value. This repository must not imply full desktop replacement before that decision gate.
+
+## Non-goals for this scaffold
+
+- No full PDF engine.
+- No production signing.
+- No proprietary dependency requirement.
+- No GNOME Shell replacement.
+- No host mutation or Linux profile wiring.
+- No production readiness claim.
+
+## Validation
+
+The scaffold must remain smokeable with:
+
+```bash
+make validate
+make smoke
+```

services/docd/package.json

@@ -1,5 +1,8 @@
 {
   "name": "docd",
   "private": true,
-  "type": "module"
+  "type": "commonjs",
+  "scripts": {
+    "smoke": "node src/derive.js"
+  }
 }

services/docd/src/derive.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// docd derive — smoke placeholder
+// Responsibility: PDF derive lane (draft → derived PDF)
+// Contracts live in SourceOS-Linux/sourceos-spec
+
+'use strict';
+
+console.log('[docd] derive: smoke OK — derive lane placeholder running');
+console.log('[docd] Input lane  : content/draft');
+console.log('[docd] Output lane : content/derived');
+console.log('[docd] Status      : placeholder (no external services required)');
+process.exit(0);

services/pdf-secure/package.json

@@ -1,5 +1,8 @@
 {
   "name": "pdf-secure",
   "private": true,
-  "type": "module"
+  "type": "commonjs",
+  "scripts": {
+    "smoke": "node src/sign-validate.js"
+  }
 }

services/pdf-secure/src/sign-validate.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// pdf-secure sign/validate — smoke placeholder
+// Responsibility: PDF sign / validate lane
+// Contracts live in SourceOS-Linux/sourceos-spec
+
+'use strict';
+
+console.log('[pdf-secure] sign-validate: smoke OK — sign/validate lane placeholder running');
+console.log('[pdf-secure] Sign input    : content/derived');
+console.log('[pdf-secure] Signed output : content/derived/pdf_signed');
+console.log('[pdf-secure] Reports       : content/reports/pdf_validation');
+console.log('[pdf-secure] Status        : placeholder (no external services required)');
+process.exit(0);