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

[mdheller]

Target repo

SourceOS-Linux/sourceos-shell

Context

sourceos-shell already exists and is the product/runtime repository for the SourceOS shell. The README states the first implementation slice is PDF-first:

• 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.

This issue turns that declared boundary into an executable first scaffold.

Scope

Implement the smallest bounded runtime scaffold that does the following:

1. Add or complete a minimal workspace/bootstrap layout for the repo.
2. Add services/docd with a minimal smokeable derive placeholder.
3. Add services/pdf-secure with a minimal smokeable sign/validate placeholder.
4. Add apps/pdf-viewer-demo with a minimal smokeable viewer/demo placeholder.
5. Add content/draft, content/derived, and content/reports directories, preserving placeholders where needed.
6. Add a Makefile or equivalent repo-native command surface with at least:
   • make validate
   • make smoke
7. Add smoke validation proving each runtime slice can be invoked without external services.
8. Update README/docs to link responsibilities back to:
   • SourceOS-Linux/sourceos-spec for contracts;
   • SociOS-Linux/source-os for Linux realization surfaces.

Acceptance criteria

• make validate passes.
• make smoke passes.
• services/docd exists and has a smokeable command/script.
• services/pdf-secure exists and has a smokeable command/script.
• apps/pdf-viewer-demo exists and has a smokeable command/script.
• content/draft, content/derived, and content/reports exist.
• README documents repo boundary and PDF-first runtime scope.
• PR body includes validation evidence.

Validation commands

Expected commands:

make validate
make smoke
find services -maxdepth 2 -type f | sort
find apps -maxdepth 2 -type f | sort
find content -maxdepth 2 -type d | sort

If repo-native commands differ, inspect and use repo-native commands.

Boundaries / non-goals

• Do not implement a full PDF engine in this issue.
• Do not add proprietary dependencies.
• Do not add secrets, tokens, credentials, private keys, or production endpoints.
• Do not modify sourceos-spec or source-os from this PR.
• Do not claim production readiness.
• Keep placeholders explicit and smoke-tested.

PR requirements

Open one PR against main. Include:

• what changed;
• exact commands run;
• pass/fail output summary;
• known gaps;
• anything blocked.