# Design Notes

> Design notes on the decisions, trade-offs, and implementation boundaries behind PIG.

---

LLMS index: [llms.txt](/llms.txt)

---

Design notes explain why PIG behaves the way it does. Each note identifies the decision date,
the implementation and release boundary, alternatives that were rejected, and the current user
documentation.

These articles are historical and architectural context. For current command syntax and behavior,
use the linked [PIG documentation](/docs/); for delivery history, use the [release notes](/release/).

---

Section pages:

- [From Human-Friendly to Agent-Native: PIG's CLI Contract](/design/agent-native-cli/): Why PIG separates human text, structured results, execution plans, and environment context instead of treating JSON as a formatting afterthought.
- [Compile, Validate, Then Commit: The Native sty conf Pipeline](/design/native-sty-conf/): Why pig sty conf treats Inventory generation as a bounded compiler pipeline with path safety, structural mutations, secret discipline, and atomic output.
- [The 70% Tuner: Defining the Boundary of pig pg tune](/design/pg-tune/): Why pig pg tune produces deterministic hardware-based core settings while refusing to present itself as complete production PostgreSQL tuning.
- [Why PIG Keeps the Cobra Command Layer Flat](/design/flat-cobra-command-layer/): The source-layout decision that keeps one top-level command in one cmd file and moves concrete behavior into cli and internal packages.
- [One Grammar for Dangerous Work: PIG's Operations CLI Safety Contract](/design/ops-cli-safety/): How PIG separates primitives from orchestrators, makes destructive intent explicit, and prevents aliases or structured output from changing operational meaning.
- [Edit the Declaration, Preserve the Document: Lossless Pigsty Inventory](/design/lossless-inventory/): Why pig inventory separates YAML semantics from source bytes so scoped edits can preserve comments, ordering, anchors, and formatting.
- [Use the CMDB Pigsty Already Has](/design/existing-cmdb-boundary/): Why PIG retired a new revision-store design and became a thin, guarded adapter to Pigsty's existing PostgreSQL CMDB.
- [A Bounded Grafana Client Instead of Dashboard Shell Scripts](/design/native-grafana-management/): Why pig sty grafana owns a small HTTP contract for dashboard lifecycle, preferences, and safe cleanup without becoming a general Grafana administration client.
- [Let Patronictl Speak for Itself](/design/patronictl-passthrough/): Why pig pt stopped mirroring Patronictl's command tree and became a transparent launcher with only a few PIG-owned local helpers.
- [PIG 2.0 Product Direction: A Proposal, Not a Release Contract](/design/pig-2-product-direction/): The proposed PIG 2.0 boundary: a stable Pigsty onboarding front door, verifiable Catalog client, and thin orchestrator that keeps deployment explicit.
- [Catalog v2 Proposal: Immutable Typed Snapshots Instead of Bigger CSV](/design/catalog-v2-snapshots/): A proposed verifiable Catalog model with typed targets, content-addressed snapshots, explicit activation, project pins, and offline import.
- [Bootstrapping a Pigsty Controller as a Recoverable Transaction](/design/native-sty-boot/): Why pig sty boot resolves sources before elevation, separates hard failures from finishing warnings, and restores repositories after failed setup.