This folder is the home for free-tree and shared-spine product “should” PRDs.
Premium-owned product should lives under pro__premium_only/docs/prd/.
Doc kinds
| Kind | Location | Wins when |
|---|---|---|
| Product PRD (free/shared) | docs/prd/*.md (this folder) |
Code disagrees with intended product behaviour |
| Product PRD (premium-owned) | pro__premium_only/docs/prd/*.md |
Premium-only behaviour disagrees with intended product |
| Subsystem contract | Colocated CONTRACT.md |
Code violates a must-guarantee interface |
| How-it-works | Colocated *.md |
Explaining current machinery (must not invent product law) |
| Glossary | Root CONTEXT.md |
Naming / ubiquitous language |
| ADRs | docs/adr/ |
Hard-to-reverse trade-offs |
| Architecture map | docs/architecture.md |
Finding the right subsystem |
Rule: New narrative product docs outside this list are forbidden. Absorb into a PRD/contract, or do not write them.
When fixing bugs: find the PRD/contract violation first, then change code. Do not “fix” by weakening the PRD without an explicit product decision.
Changing a deep-module interface requires PRD/contract update + tests in the same change.
| Slug | Doc | Owns |
|---|---|---|
| product | product.md | North star, browser-side optimize, audience, success |
| free-vs-premium | free-vs-premium.md | Packaging cut, upsell, matrix |
| upload-interception | upload-interception.md | Drop/select capture, locations, synthetic re-dispatch |
| conversion-engine | conversion-engine.md | Router, Converter contract, image path, filter seams |
| attachment-intelligence | attachment-intelligence.md | Metadata queue, sidebar, metabox, stats, notices |
| bulk-library | bulk-library.md | Shared list/progress; free upsell; points to premium mutate |
| settings-and-freemium-ux | settings-and-freemium-ux.md | Options schema, settings UI, upsells, stealth surface |
| Slug | Doc |
|---|---|
| licensing-and-updates | pro__premium_only/docs/prd/licensing-and-updates.md |
| bulk-library-premium | pro__premium_only/docs/prd/bulk-library-premium.md |
| lqip | pro__premium_only/docs/prd/lqip.md |
| Area | Doc |
|---|---|
| Upload interception | src/admin/js/media-manager/CONTRACT.md |
| Conversion engine | src/shared/converters/CONTRACT.md |
| Attachment intelligence (PHP) | src/admin/CONTRACT.md |
| Settings UI shell | src/admin/js/page/CONTRACT.md |
CONTEXT.md+ this index + product + free-vs-premium- Upload interception + conversion engine (+ contracts)
- Attachment intelligence + bulk-library (+ contracts)
- Settings-and-freemium-ux
- Premium PRDs/contracts under
pro__premium_only/ - Align how-it-works; open GitHub issues for deepen/refactor opportunities
Refactors that improve locality without changing PRD promises: