ADR-007: public/ for publishable packages

Context

Aucert has customer-facing artifacts that will be published to package registries (npm, PyPI) — starting with the CLI tool. These packages need clear separation from internal code to prevent accidental exposure of internal APIs, types, or implementation details.

The CLI (aucert command) is the primary customer interface during Phase 1, supporting aucert run, aucert status, and aucert init commands.

Decision

Place all publishable, customer-facing packages under a top-level public/ directory. This creates a clear physical boundary between internal code and code that will be distributed to customers.

Structure

public/
  cli/                    # aucert CLI tool
    spec/CLI.md           # CLI specification
    package.json          # Published to npm as @aucert/cli
    src/
    tests/
  sdk-node/               # Future: Node.js SDK (Phase 2+)
  sdk-python/             # Future: Python SDK (Phase 2+)

Alternatives considered

Option	Pros	Cons
public/ directory (chosen)	Clear boundary, easy to audit what's published, content boundary scanner can target this	Extra directory level
Packages inside frontend/packages/	Closer to existing pnpm workspace	Mixes internal UI packages with customer-facing code
Separate repository	Complete isolation	Breaks monorepo benefits (ADR-001), duplicates CI
packages/ top-level	Common convention	Ambiguous: "packages" could mean internal or external

Consequences

What becomes easier

• Content boundary enforcement: CI scans public/ to prevent internal API leakage
• Documentation site can reference public/cli/spec/CLI.md for command reference
• Clear for new contributors: "code in public/ is what customers see"
• Publishing pipeline only needs to watch public/ for releases

What becomes harder

• CLI code in public/cli/ can't directly import backend internals (must use published APIs)
• Need to maintain versioning and changelog for published packages
• Phase 2/3 SDKs must not be created prematurely (hard rule)