docs: split customer docs from internal project docs (#828)

Co-authored-by: proof-dev <proof-dev@socialproof.dev>

Author: proof-developer[bot]

README.md

@@ -25,7 +25,7 @@ apps/
 blog/         Blog (CF Pages)
 docs/         Docs site
 infra/        IaC / config
-project/      Strategy docs, roadmap, status
+project-docs/  Internal strategy docs, runbooks, roadmap, status
 ```
 
 ## Stack
@@ -118,11 +118,11 @@ cd apps/worker && npm run test:watch
 
 ---
 
-## Project Docs
+## Internal Project Docs
 
 | Doc | Description |
 |-----|-------------|
-| [project/vision.md](project/vision.md) | Product vision, positioning, what we build |
-| [project/roadmap.md](project/roadmap.md) | Current sprint and milestones |
-| [project/user-stories.md](project/user-stories.md) | Expected behaviour — use for QA and test writing |
-| [project/activation-first-strategy.md](project/activation-first-strategy.md) | Why activation > conversion right now |
+| [project-docs/vision.md](project-docs/vision.md) | Product vision, positioning, what we build |
+| [project-docs/roadmap.md](project-docs/roadmap.md) | Current sprint and milestones |
+| [project-docs/user-stories.md](project-docs/user-stories.md) | Expected behaviour — use for QA and test writing |
+| [project-docs/activation-first-strategy.md](project-docs/activation-first-strategy.md) | Why activation > conversion right now |

docs/README.md

@@ -0,0 +1,32 @@
+# `docs/` vs `project-docs/`
+
+This repo has two documentation homes on purpose:
+
+- `docs/` = customer-facing product documentation and public-facing support content
+- `project-docs/` = internal project documentation, playbooks, runbooks, strategy notes, ADRs, and working docs
+
+## Put files in `docs/` when
+
+The content is written for customers, prospects, or external users of SocialProof.
+Examples:
+- getting started / quickstart guides
+- embedding instructions
+- collecting testimonials
+- public product guides and help content
+
+## Put files in `project-docs/` when
+
+The content is written for the team operating or building SocialProof.
+Examples:
+- deployment runbooks
+- launch plans and distribution strategy
+- internal status logs
+- ADRs and architectural notes
+- postmortems and activation analyses
+- SOPs / playbooks / how-tos for internal operations
+
+## Notes
+
+- If a document teaches a customer how to use the product, it belongs in `docs/`.
+- If a document explains how we run, build, ship, or decide things internally, it belongs in `project-docs/`.
+- When in doubt, optimize for audience: external user → `docs/`; internal operator/builder → `project-docs/`.

handbook/who-does-what.md

@@ -9,7 +9,7 @@ A quick reference for which creature handles which type of work on the Vouch / P
 ### CEO (this creature)
 - Owns vision, roadmap, and priorities
 - Files issues to assign work to the team
-- Writes docs in `project/` — vision, roadmap, architecture decisions, status updates, playbooks
+- Writes docs in `project-docs/` — vision, roadmap, architecture decisions, status updates, playbooks
 - Reviews PRs with comments — does NOT merge PRs authored by dev/ops/marketing
 - Escalates blockers to @rsdouglas via `needs-human` issues
 - **Does NOT write code, HTML, configs, or implementation artifacts of any kind**