Community Safe

TL;DR

Private data stays private. 🔴 The channel guard does NOT block PII — it blocks pro/private keywords and credential file shapes; emails, API keys and IP addresses pass straight through. Run a PII check yourself before publishing. Protocols and muscles must be generic (no emails, paths, project names). When sharing to the hub, strip absolute paths and private repo references. Private data belongs in .soma/secrets/, identity files, or env vars.

How Soma keeps private data out of public content. The guard catches a NARROW mechanical class —

this protocol covers the judgment, and names the check the guard will not run for you.

What's Automated — and what isn't

🔴 Nothing blocks PII at push time. Do not rely on a hook to catch a leaked email.

Corrected 2026-08-10. This protocol previously stated: *"If it finds PII in a public repo

commit, it blocks the push" — listing emails, IP addresses and API keys as blocked. *That was

false**, and false in the reassuring direction, which is the dangerous one: it credited the

pre-push guard with a job a different, non-blocking, on-demand script does, and credited

nobody with IP addresses. Verified by reading the guard: it contains no email or API-key

matching at all.

Two different mechanisms, and only one of them blocks:

what	when	blocks?
Pro/private keywords (vault paths, private-tier names, absolute home paths)	pre-push hook	✅ yes
Credential FILE SHAPES (id_rsa, *.pem, credentials.json, .env.local)	pre-push hook	✅ yes
_-prefixed branch guard	pre-push hook	✅ yes
Email addresses, API keys	on-demand PII audit only — no hook wiring	❌ no
IP addresses	—	❌ detected by nothing

⇒ Run a PII scan over your diff yourself before publishing. The channel guard will not do it for

you, and a clean push is not evidence your diff is PII-free.

🔑 The general lesson, worth more than this one file: a control that is documented as blocking

and is implemented as advisory is worse than no control — it buys confidence it has not earned.

When a doc tells you something is enforced, read the enforcer.

What Needs Judgment

The guard catches obvious shapes. These need your awareness:

Private data belongs in:

• .soma/secrets/ (gitignored)
• .soma/body/soul.md (project-local, not pushed to public repos)
• Environment variables / .env files (gitignored)

Protocols and muscles must be generic:

• ✅ "Read before edit" — universal pattern
• ❌ "User prefers tabs over spaces" — personal preference in a public protocol
• ✅ "Check git config before committing" — universal
• ❌ "Set email to user@example.com" — private data

When sharing to the hub:

• Strip all absolute paths
• Remove references to private repos, internal tools, specific projects
• Keep patterns universal — if it only works for your setup, it's local, not community

Source

• Channel guard — the pre-push hook: keyword and filename shapes only
• Guard extension — soma-guard (path/command gates)
• PII audit — on demand via soma-audit pii; never blocks, never runs itself

Community Safe

TL;DR

Private data stays private. Channel-guard blocks PII pre-push. Your judgment covers the rest: protocols and muscles must be generic (no emails, paths, project names). When sharing to hub, strip absolute paths and private repo references. Private data belongs in .soma/secrets/, identity files, or env vars.

How Soma keeps private data out of public content. The channel-guard script catches leaks mechanically — this protocol covers the judgment that prevents creating them.

What's Automated

soma-channel-guard.sh — pre-push hook that scans for:

• Email addresses, IP addresses, API keys
• Absolute paths containing usernames
• Private repo references
• .soma/secrets/ content

If it finds PII in a public repo commit, it blocks the push.

What Needs Judgment

The script catches obvious leaks. These need your awareness:

Private data belongs in:

• .soma/secrets/ (gitignored)
• .soma/body/soul.md (project-local, not pushed to public repos)
• Environment variables / .env files (gitignored)

Protocols and muscles must be generic:

• ✅ "Read before edit" — universal pattern
• ❌ "User prefers tabs over spaces" — personal preference in public protocol
• ✅ "Check git config before committing" — universal
• ❌ "Set email to user@example.com" — private data

When sharing to the hub:

• Strip all absolute paths
• Remove references to private repos, internal tools, specific projects
• Keep patterns universal — if it only works for your setup, it's local, not community

Source

• Channel guard: scripts/soma-channel-guard.sh
• Guard extension: extensions/soma-guard.ts
• PII audit: scripts/soma-audit.sh → PII check

---

Community-Safe Content Protocol

TL;DR

• Community protocols, muscles, skills, and templates must be generic and reusable
• Never include: emails, home paths, API keys, tokens, secrets, hardcoded usernames, org-specific URLs
• Private data belongs in: USER.md, .env, .soma/secrets/, project memory, identity files
• Muscles encode patterns (how to do things). Specifics live in knowledge (about this user/project)
• Before sharing: strip all project-specific references. Replace with generic examples.

Rule

Community assets are loaded into agent context across many users' machines. They must be safe, generic, and useful to anyone.

What MUST NOT be in community assets

Category	Examples	Where it belongs instead
Personal identity	Email, name, username	identity.md, USER.md
Paths	/Users/username/, ~/Gravicity/	Project config, .env
Secrets	API keys, tokens, passwords	.soma/secrets/, .env
Org-specific URLs	mycompany.slack.com, internal dashboards	Project memory
Hardcoded repos	meetsoma/soma-agent (unless it's an example)	Replace with your-org/your-repo
Test counts/data	"192 tests passing"	Stale immediately — use generic process
Internal decisions	"We chose React because the lead prefers it"	Project STATE.md

What SHOULD be in community assets

Category	Examples
Patterns	"Run tests after any file removal"
Processes	"Branch → PR → CI → review → merge"
Anti-patterns	"Don't delete working scripts during cleanup"
Decision frameworks	"Three verbs in order: keep, move, delete"
Generic commands	git checkout --theirs <files> (not git checkout --theirs package.json)

The Pattern vs Knowledge Split

This is the core principle:

MUSCLE (community-safe):
  "After any code removal, run all test suites and grep for orphaned references."
  → This is a PATTERN. Works for anyone.

KNOWLEDGE (private):
  "Our test suite is in tests/*.sh, we have 192 tests, the CLI dep test
   needs soma binary installed."
  → This is KNOWLEDGE about a specific project. Stays local.

A muscle that says "run pnpm test" is fine — that's a generic command. A muscle that says "run bash tests/test-protocols.sh && bash tests/test-settings.sh" is too specific — those are project-local paths.

Before Sharing

Checklist before exporting to community:

1. [ ] grep -E '(/Users/|/home/|~/|@.*\.(com|ai|io))' my-muscle.md — no personal paths or emails
2. [ ] grep -Ei '(sk-|ghp_|npm_|token|secret|password)' my-muscle.md — no secrets
3. [ ] Replace specific repo names with generic examples
4. [ ] Replace specific test counts, file names, paths with generic descriptions
5. [ ] Set heat: 0 (muscles) — users control their own heat
6. [ ] Add author: and license: fields
7. [ ] Verify it makes sense to someone who's never seen your project

When to Apply

• When running /sync-community export
• When writing a PR to meetsoma/community
• When reviewing someone else's PR to the community repo
• When deciding what goes in a muscle vs what goes in project memory

When NOT to Apply

• Project-local muscles (.soma/memory/muscles/) can be as specific as you want
• Identity files are inherently personal
• This protocol only applies to content destined for community sharing

Community-Safe Content Protocol

TL;DR

• Community protocols, muscles, skills, and templates must be generic and reusable
• Never include: emails, home paths, API keys, tokens, secrets, hardcoded usernames, org-specific URLs
• Private data belongs in: USER.md, .env, .soma/secrets/, project memory, identity files
• Muscles encode patterns (how to do things). Specifics live in knowledge (about this user/project)
• Before sharing: strip all project-specific references. Replace with generic examples.

Rule

Community assets are loaded into agent context across many users' machines. They must be safe, generic, and useful to anyone.

What MUST NOT be in community assets

Category	Examples	Where it belongs instead
Personal identity	Email, name, username	identity.md, USER.md
Paths	/Users/username/, ~/Gravicity/	Project config, .env
Secrets	API keys, tokens, passwords	.soma/secrets/, .env
Org-specific URLs	mycompany.slack.com, internal dashboards	Project memory
Hardcoded repos	meetsoma/soma-agent (unless it's an example)	Replace with your-org/your-repo
Test counts/data	"192 tests passing"	Stale immediately — use generic process
Internal decisions	"We chose React because the lead prefers it"	Project STATE.md

What SHOULD be in community assets

Category	Examples
Patterns	"Run tests after any file removal"
Processes	"Branch → PR → CI → review → merge"
Anti-patterns	"Don't delete working scripts during cleanup"
Decision frameworks	"Three verbs in order: keep, move, delete"
Generic commands	git checkout --theirs <files> (not git checkout --theirs package.json)

The Pattern vs Knowledge Split

This is the core principle:

MUSCLE (community-safe):
  "After any code removal, run all test suites and grep for orphaned references."
  → This is a PATTERN. Works for anyone.

KNOWLEDGE (private):
  "Our test suite is in tests/*.sh, we have 192 tests, the CLI dep test
   needs soma binary installed."
  → This is KNOWLEDGE about a specific project. Stays local.

A muscle that says "run pnpm test" is fine — that's a generic command. A muscle that says "run bash tests/test-protocols.sh && bash tests/test-settings.sh" is too specific — those are project-local paths.

Before Sharing

Checklist before exporting to community:

1. [ ] grep -E '(/Users/|/home/|~/|@.*\.(com|ai|io))' my-muscle.md — no personal paths or emails
2. [ ] grep -Ei '(sk-|ghp_|npm_|token|secret|password)' my-muscle.md — no secrets
3. [ ] Replace specific repo names with generic examples
4. [ ] Replace specific test counts, file names, paths with generic descriptions
5. [ ] Set heat: 0 (muscles) — users control their own heat
6. [ ] Add author: and license: fields
7. [ ] Verify it makes sense to someone who's never seen your project

When to Apply

• When running /sync-community export
• When writing a PR to meetsoma/community
• When reviewing someone else's PR to the community repo
• When deciding what goes in a muscle vs what goes in project memory

When NOT to Apply

• Project-local muscles (.soma/memory/muscles/) can be as specific as you want
• Identity files are inherently personal
• This protocol only applies to content destined for community sharing