marketing: build public product evidence and demo system

docs/README.md

@@ -33,5 +33,6 @@ Projects installed with v0.4.1 that report `Unrecognized key: rules` should foll
 * [Contributing Guidelines](09-contributing/contribution-overview.md)
 * [Real-World Examples and Tutorials](10-examples/README.md)
 * [Appendices and Traceability](11-appendices/glossary.md)
+* [Product Evidence and Public Demonstration](../marketing/README.md)
 
 For the complete page tree, see [SUMMARY.md](SUMMARY.md).

marketing/README.md

@@ -0,0 +1,101 @@
+# Product Evidence and Public Demonstration
+
+This section defines how Development Kit should prove its value publicly through real screenshots, short demonstrations, a complete product video, and investor-facing evidence.
+
+## Objective
+
+The evidence system must answer four questions quickly:
+
+1. What problem does Development Kit solve?
+2. What does the product actually do inside a supported coding agent?
+3. What controls prevent unsafe or unverified automation?
+4. What measurable engineering assets and validation systems support the product claim?
+
+## Audience tracks
+
+### Public and prospective users
+
+Show that installation is simple, the recommended workflow is understandable, and the product guides users without requiring them to memorize every command.
+
+Primary evidence:
+
+- Quick installation animation
+- OpenCode startup menu screenshot
+- 90-second overview video
+- Clear link to the public npm package
+
+### Developers and technical evaluators
+
+Show deterministic lifecycle state, specialist routing, approval gates, tests, evaluations, and release validation.
+
+Primary evidence:
+
+- Autopilot lifecycle status screenshot
+- Approval-gate screenshot
+- Release-validation screenshot
+- Technical walkthrough with commands visible
+- Links to runtime, tests, evaluations, and architecture documentation
+
+### Potential investors and strategic partners
+
+Show the category problem, differentiated workflow architecture, product defensibility, repeatability, and evidence that Development Kit is a maintained public product rather than a prompt collection.
+
+Primary evidence:
+
+- Two-minute investor narrative
+- Architecture and workflow diagram
+- Current component and validation metrics
+- Public npm and GitHub release proof
+- Roadmap and adoption instrumentation plan
+
+## Evidence hierarchy
+
+Use the following order on public pages:
+
+1. One strong hero screenshot or clickable demo thumbnail
+2. One short animated demonstration
+3. Three to five focused screenshots with outcome captions
+4. One full product walkthrough
+5. Technical proof links and validation metrics
+6. Investor narrative and roadmap material
+
+Do not overload the root README with every asset. The README should create understanding and confidence quickly, then link to a deeper showcase page.
+
+## Required deliverables
+
+- [Capture and publish checklist](capture-and-publish-checklist.md)
+- [Capture plan](capture-plan.md)
+- [Repeatable demo project](demo-project-brief.md)
+- [Video storyboard and narration](video-storyboard.md)
+- [Investor demonstration narrative](investor-demo-narrative.md)
+- [README showcase template](readme-showcase-template.md)
+- [Recording and privacy checklist](recording-checklist.md)
+- [Product showcase structure](product-showcase.md)
+- [Media standards](../media/README.md)
+
+## Acceptance criteria
+
+The first evidence release is ready when:
+
+- Five canonical screenshots exist and use consistent dimensions and styling.
+- Two short repository-friendly demonstrations exist.
+- A captioned 60 to 90 second public overview video is hosted at a stable URL.
+- The root README contains a concise `See Development Kit in action` section.
+- The showcase page explains each function using real output.
+- All assets are free of secrets, private repository data, personal notifications, and unrelated account information.
+- Every claim shown in a caption is supported by the displayed product state or linked source documentation.
+- The documentation and link validators pass.
+
+## Success measures
+
+After publication, track:
+
+- README-to-demo click-through rate
+- Demo completion rate
+- Repository stars and forks
+- npm downloads
+- Issue and discussion quality
+- Installation failures reported by environment
+- Conversion from demo viewers to repository visitors or package users
+
+These measures should be introduced only after a privacy-conscious analytics approach is approved.

marketing/capture-and-publish-checklist.md

@@ -0,0 +1,106 @@
+# Capture and Publish Checklist
+
+Use this checklist to complete the first Development Kit public evidence release. Keep the pull request in draft until every required gate is complete.
+
+## 1. Record the evidence environment
+
+- [ ] Use the dedicated `RelayBoard` demo workspace described in [the demo project brief](demo-project-brief.md).
+- [ ] Restore the clean starter commit and remove previous `.development-kit` state.
+- [ ] Confirm the workspace contains only synthetic data.
+- [ ] Record the Development Kit, OpenCode, Node.js, and operating-system versions.
+- [ ] Record the starter repository commit, capture date, and exact commands used.
+- [ ] Record every crop, annotation, redaction, shortened sequence, or speed change.
+- [ ] Complete an unrecorded rehearsal, reset the workspace, and then make the final captures.
+
+## 2. Capture the five canonical screenshots
+
+- [ ] `media/screenshots/npm-installation.png`
+  - Run `npm view development-kit version`.
+  - Run `npx development-kit@0.4.2 init --opencode --dry-run`.
+  - Show the public version and generated file plan.
+  - Export as a 1600 x 900 PNG.
+- [ ] `media/screenshots/opencode-startup-menu.png`
+  - Open the clean demo workspace in OpenCode.
+  - Show the recommended Development Kit guided-workflow entry.
+  - Export as a 1600 x 900 PNG.
+- [ ] `media/screenshots/autopilot-lifecycle-status.png`
+  - Start `/dk-autopilot`.
+  - Show the current lifecycle stage, selected action, and next transition.
+  - Export as a 1600 x 900 PNG.
+- [ ] `media/screenshots/approval-gate.png`
+  - Reach a safe approval boundary for a push, pull request, release, or publication action.
+  - Show the explicit authorization request without executing a real consequential operation.
+  - Export as a 1600 x 900 PNG.
+- [ ] `media/screenshots/release-validation.png`
+  - Run `npm run release:validate` from the Development Kit repository.
+  - Show the final passing framework, plugin, documentation, OpenCode, Autopilot, and evaluation summary.
+  - Export as a 1600 x 900 PNG.
+
+## 3. Produce the short demonstrations
+
+- [ ] `media/demos/quick-install.webp`
+  - Show the npm version query, OpenCode dry run, and generated file plan.
+  - Target 10 to 15 seconds, with readable captions, under 8 MB.
+- [ ] `media/demos/autopilot-overview.webp`
+  - Show OpenCode startup, the guided entry, `/dk-autopilot`, lifecycle selection, an approval pause, and state evidence.
+  - Target 20 to 35 seconds, with readable captions, under 10 MB.
+
+Cut both demonstrations from the same reviewed master recording where practical so commands, versions, and visual treatment remain consistent.
+
+## 4. Publish the full demonstration
+
+- [ ] Edit the reviewed master recording to 75 to 90 seconds.
+- [ ] Use real Development Kit execution for every product scene.
+- [ ] Add captions and a written transcript.
+- [ ] Keep commands and outcomes readable at normal playback size.
+- [ ] Disclose materially shortened or accelerated sequences.
+- [ ] End with the repository, npm package, and captured version.
+- [ ] Publish to a stable public URL that works without authentication.
+- [ ] Retain the unedited source recording privately for authenticity review.
+
+## 5. Produce the promotional artwork
+
+- [ ] `media/social/product-demo-thumbnail.png`
+  - Use a real product capture as the interface background.
+  - Add Development Kit branding, a play icon, and `Watch the 90-second demo`.
+  - Export as a 1280 x 720 PNG.
+- [ ] `media/social/repository-preview.png`
+  - Include the product name, concise value proposition, nine-stage lifecycle, supported environments, and captured public version.
+  - Use real product imagery wherever an interface is shown.
+  - Export as a 1280 x 640 PNG under 1 MB.
+  - Configure it as the GitHub repository social-preview image.
+
+## 6. Review privacy, accuracy, and authenticity
+
+Complete [the recording and privacy checklist](recording-checklist.md), including these release blockers:
+
+- [ ] All displayed output comes from real execution.
+- [ ] Commands and versions match the public release.
+- [ ] No secret, token, API key, email address, private URL, account detail, notification, or unrelated repository is visible.
+- [ ] No unnecessary personal filesystem path is visible.
+- [ ] Cropping does not hide warnings, failures, or relevant context.
+- [ ] Annotations do not alter the underlying evidence.
+- [ ] Captions make only claims supported by the visible evidence.
+- [ ] Approval gates are shown accurately and are not bypassed.
+- [ ] Every image has concise descriptive alt text.
+- [ ] A separate second review has checked privacy and accuracy.
+
+## 7. Activate the public documentation
+
+- [ ] Replace planning language in [the product showcase](product-showcase.md) with the reviewed evidence, captions, captured version, capture date, and supporting links.
+- [ ] Replace `PUBLIC_VIDEO_URL` in [the README showcase template](readme-showcase-template.md) with the verified public video URL.
+- [ ] Remove the intentional spaces from the inactive Markdown in the template.
+- [ ] Insert the activated `See Development Kit in action` section into the root README after `Current release` and before `What you get`.
+- [ ] Verify the documentation-home link to this marketing workspace.
+- [ ] Verify every image, animation, video, documentation, npm, and GitHub link.
+- [ ] Confirm that no placeholder URL, inactive Markdown, broken reference, or `coming soon` claim remains.
+
+## 8. Run the final merge gate
+
+- [ ] Run `npm run release:validate` against the final asset commit.
+- [ ] Confirm the entire suite passes.
+- [ ] Confirm large master video files are not committed or included in the npm package.
+- [ ] Record the final evidence metadata and validation result in the pull request.
+- [ ] Request final evidence review.
+- [ ] Mark the pull request ready only after all preceding gates pass.
+- [ ] Merge only after the evidence, privacy, accuracy, links, and validation results are approved.

marketing/capture-plan.md

@@ -0,0 +1,119 @@
+# Evidence Capture Plan
+
+## Demo workspace
+
+Use a dedicated folder such as:
+
+```text
+C:\Users\SSTECH\developments\dk-public-demo
+```
+
+The workspace should contain only files created for the demonstration. Do not use customer repositories, personal projects, production credentials, or private documents.
+
+## Preparation
+
+1. Update Development Kit and confirm the public package version.
+2. Use the current stable OpenCode release.
+3. Set the display to 1920 x 1080 where practical.
+4. Use a readable editor and terminal font size, typically 18 to 22 px.
+5. Disable notifications and hide bookmarks, personal tabs, account details, and taskbar items that reveal unrelated information.
+6. Use a consistent light or dark theme across all captures.
+7. Clear terminal history where it could expose private paths or commands.
+8. Prepare a small, neutral demo project such as a task-tracking API or simple dashboard.
+
+## Capture sequence
+
+### Capture 1: Public npm installation
+
+Show:
+
+```powershell
+npm view development-kit version
+npx development-kit@0.4.2 init --opencode --dry-run
+```
+
+Evidence goal: Development Kit is publicly available and the installation plan is understandable before files are written.
+
+Output assets:
+
+- `media/screenshots/npm-installation.png`
+- `media/demos/quick-install.webp`
+
+### Capture 2: OpenCode startup experience
+
+Open the demo workspace in OpenCode and capture the Development Kit recommended startup option.
+
+Evidence goal: The user can enter the complete workflow without learning every command first.
+
+Output asset:
+
+- `media/screenshots/opencode-startup-menu.png`
+
+### Capture 3: Autopilot lifecycle state
+
+Start:
+
+```text
+/dk-autopilot
+```
+
+Capture the current lifecycle stage, selected action, and the transition to the next stage.
+
+Evidence goal: Development Kit coordinates a defined lifecycle rather than producing an unstructured response.
+
+Output assets:
+
+- `media/screenshots/autopilot-lifecycle-status.png`
+- `media/demos/autopilot-overview.webp`
+
+### Capture 4: Human approval gate
+
+Use a safe demonstration action that reaches a consequential approval boundary, such as preparing a pull request, release, or remote push without executing it automatically.
+
+Evidence goal: Development Kit stops for explicit authorization before consequential operations.
+
+Output asset:
+
+- `media/screenshots/approval-gate.png`
+
+Do not demonstrate approvals using real production credentials or a repository where accidental execution would be harmful.
+
+### Capture 5: Verification evidence
+
+From the Development Kit source repository, show:
+
+```powershell
+npm run release:validate
+```
+
+Capture the final summary showing the framework, documentation, OpenCode, Autopilot, and evaluation gates passing.
+
+Evidence goal: Product claims are backed by automated validation.
+
+Output asset:
+
+- `media/screenshots/release-validation.png`
+
+## Optional advanced captures
+
+- Pause and resume across sessions
+- Stale artifact detection after an upstream change
+- Rejection of an invalid approval token
+- Recovery from an interrupted action lease
+- Manual command fallback from `/dk-autopilot`
+- Antigravity installation and startup experience
+- GitHub release and npm publication workflow
+
+## Capture order
+
+Capture static screenshots first. Then record the full video in one continuous session using the same workspace and visual settings. The short animations should be cut from the full recording so the evidence remains consistent.
+
+## Review before publication
+
+A second review should verify:
+
+- Commands and version numbers are correct.
+- No secret, email, username, private path, browser profile, or unrelated repository is visible.
+- Captions describe only what the image proves.
+- The workflow shown matches current documentation.
+- The recording does not imply that approval gates were bypassed.