molecule-core/docs/internal-content-policy.md

Internal content policy

The Molecule-AI/molecule-monorepo repo is public. Anything internal (positioning, competitive briefs, sales playbooks, PMM/press drip, draft campaigns, raw research notes, ops runbooks, retrospectives) lives in Molecule-AI/internal.

This page is the canonical decision tree.

Quick decision

"I'm an agent (or human) about to write a markdown file. Where does it go?"

If the artifact is…	Put it in…
Competitive brief, market analysis, raw research notes	Molecule-AI/internal/research/
PMM positioning draft, sales playbook, press release pre-publish	Molecule-AI/internal/marketing/
Draft campaign asset (still iterating, not yet customer-visible)	Molecule-AI/internal/marketing/campaigns/
Roadmap discussion, planning doc, retrospective	Molecule-AI/internal/PLAN.md or Molecule-AI/internal/retrospectives/
Runbook, ops procedure, incident postmortem	Molecule-AI/internal/runbooks/
Public-ready blog post (final draft, ready to ship to docs site)	Molecule-AI/molecule-monorepo/docs/blog/
Public-ready tutorial / quickstart	Molecule-AI/molecule-monorepo/docs/tutorials/
Public DevRel content (code samples, demos for users)	Molecule-AI/molecule-monorepo/docs/devrel/
API reference, architecture docs for external developers	Molecule-AI/molecule-monorepo/docs/api/
Code, tests, infrastructure	wherever is appropriate inside this repo

Rule of thumb: "Would I be comfortable if a competitor / journalist / customer read this verbatim today?" — yes → monorepo/docs/. No / not yet → internal/.

Why

This repo is publicly indexable. Anything pushed here is permanently in git history, search-engine indexed, and accessible to anyone who clones. Past incidents (audit 2026-04-23) found:

• Competitive teardowns of CrewAI / Paperclip / VoltAgent at root /research/
• 45 marketing artifacts at root /marketing/ including pmm/positioning.md, press/launch.md, sales/enablement.md
• 31 draft campaign files at /docs/marketing/
• Junk temp files at root: comment-1172.json, tick-reflections-temp.md

All migrated to internal/from-monorepo-2026-04-23/ for curator triage.

Enforcement

Three layers, all required:

1. .gitignore — blocks the directories at git add time. Quietest layer; doesn't fire if someone uses git add -f.
2. CI workflow block-internal-paths.yml — fails any PR that adds a forbidden path. Mechanical backstop. Cannot be bypassed without editing the workflow + PR review.
3. Agent prompts — SHARED_RULES.md rule (in molecule-ai-org-template-molecule-dev) tells every agent role to write internal content to Molecule-AI/internal directly via gh repo clone + commit + PR. This is the prevention-at-source layer.

If you're hitting the CI gate and your file genuinely belongs in this repo, edit FORBIDDEN_PATTERNS in the workflow with reviewer signoff. Don't work around the gate by renaming files.

How to write to the internal repo (for agents)

# One-time clone (idempotent — re-running is a no-op)
mkdir -p ~/repos
test -d ~/repos/internal || gh repo clone Molecule-AI/internal ~/repos/internal

cd ~/repos/internal
git pull origin main
mkdir -p research
cat > research/<slug>.md <<EOF
# <title>

…content…
EOF

git checkout -b <agent-role>/research-<slug>
git add research/<slug>.md
git commit -m "research: add <slug>"
git push -u origin HEAD
gh pr create --base main --fill

Yes, this is more steps than cd molecule-monorepo && git add research/foo.md. That cost is intentional: the friction is the point. Public space and internal space are different products with different audiences and different durability guarantees.