Repository & Storage

The .ghostable/ directory is project state, not a local cache. It is intended to be committed, reviewed, branched, and merged with the application:

.ghostable/
├── ghostable.yaml
├── policy.json
├── devices/
├── access-requests/
├── environments/
│   └── production/
│       ├── access/
│       ├── keys/
│       └── values/
├── events/
├── schema.yaml
├── schemas/
└── hygiene.yaml

Values are encrypted, while device, policy, key metadata, access, activity, and suppression records are signed so tampering can be detected. Deleting or hand-editing these files can invalidate the project state; use CLI commands whenever one exists.

Each device has an Ed25519 signing key and X25519 encryption key. Public device records are committed. Private material is stored outside the repository:

File-backed identity directories use 0700 permissions and identity files use 0600 on Unix-like systems.

Encryption protects secret values, not all context. Repository readers may see project and environment names, public device labels, access roles, variable key names, annotations, change reasons, event timing, and schema descriptions.

Review Ghostable changes alongside the code that consumes them:

$ ghostable validate --env staging
$ ghostable review
$ git diff -- .ghostable
$ git add .ghostable && git commit -m "Update staging configuration"
 

Signed records do not remove the need for code review. A valid signature proves which authorized identity produced a record; it does not prove that the change is wise or that a reviewer should merge it.

Treat each signed JSON record as an indivisible unit. Never splice signatures, policy fields, wrapped keys, ciphertext, or event content from both sides of a conflict: the resulting record will not verify, and mixing environment-key generations can make state unreadable.

1. Stop Ghostable writes and identify every unresolved path under .ghostable/.
2. Choose one complete, reviewed version of each conflicted record. For rotations, keep the policy, environment key metadata, grants, and values from the same authoritative generation.
3. Finish the merge or rebase, then rerun the discarded Ghostable operation from the resolved branch instead of recreating its JSON by hand.
4. Run status, validation, review, and a normal Git diff before committing the resolution.

$ git diff --name-only --diff-filter=U -- .ghostable
$ ghostable status
$ ghostable validate --env staging
$ ghostable review
$ git diff -- .ghostable