Reset device data — start fresh with new identities

This walkthrough covers the "nuke and start clean" workflow for an OctoMY device when its registries and on-disk state have drifted out of sync with each other. By the end you'll have a freshly initialised device with no inherited sentients, nodes, hives, or audit data.

When to do this

The startup state machine + registry self-heal cover most drift cases automatically. Reach for this guide only when:

• The sentient picker keeps mis-labelling Shadow vs Secured even after mounting each sentient.
• You're debugging an issue that's confounded by inherited state.
• You changed the on-disk data format and need a clean slate to verify the new layout.

Routine UX issues (logout-then-login, switching identities, etc.) do not need a wipe.

1. Locate the data folder

OctoMY stores per-app data under your user data location. The exact path depends on your app:

On macOS the parent is ~/Library/Application Support/OctoMY™/; on Windows it's %APPDATA%/OctoMY™/.

You can also override the location at launch with --basedir /path/to/wherever if you want to keep multiple device profiles side by side.

2. Back up first

The folder holds your sentient hives — the encrypted vaults that own your identities. Nuking destroys them. Back up first if there's any chance you'll want to recover later:

cp -r "~/.local/share/OctoMY™/OctoMY™ hub" \
      "~/.local/share/OctoMY™/OctoMY™ hub.backup-$(date +%F)"

3. Shut down the app

The store files are open while the app is running. Quit normally — do not kill -9 unless you know the SaveState cascade has already drained (the lanyard's progress dot stops spinning).

4. Wipe the folder(s)

rm -rf "~/.local/share/OctoMY™/OctoMY™ hub"

Optional but recommended for a truly clean state: wipe the matching settings folder too. App settings live separately under ~/.config/ and persist some flags that aren't strictly UI preferences — most notably the pairing-skipped boolean. If you leave them in place a brand-new device will inherit "pairing was skipped" from your previous identity and the unboxing wizard's pairing chip will light amber before you've done anything.

rm -rf "~/.config/OctoMY™/OctoMY™ hub"

If you do want to keep window positions, debug toggles, etc., you can edit the settings JSON in place and clear only the identity-scoped keys (look for pairing-skipped, unboxing-*).

5. Relaunch + walk through unboxing

When you start the app again the StartupStateMachine sees the empty folder and walks you through:

1. Welcome / sentient choice — Create new, Import from phrase, or Import from another device.
2. Sentient creation — your first sentient lands as a shadow (no user-set passphrase yet, auto-mounts with the public default).
3. Security upgrade prompt — sets your real passphrase. This is the call that writes device_owner.json AND flips the registry's isShadow=false. Both stores stay in sync.
4. Node creation — agent/remote/hub identity inside the sentient.

After unboxing the sentient picker will correctly read Secured; the lanyard chip will match. No self-heal needed because the data is born pristine.

What changed in the persistence layer

If you arrived here from a debugging session, the canonical sources of truth for "is this sentient secured?" are now centralised in libhive/hive/SentientSecurity.hpp. The picker, lanyard tooltip and the security-upgrade gate all route through sentientSecurityFor(), which checks three signals in priority order:

1. device_owner.json next to the hive's storePath (strongest — disk truth).
2. SentientEntry.passphrase — any non-empty, non-default value reads as user-set.
3. SentientEntry.isShadow registry flag (weakest — legacy fallback).

The security cases of the testSentientRegistry test suite lock this contract in place; a regression on any of the three signals fails the build.

Future on-disk format changes

When we change the data layout in a future release, the right pattern is:

1. Bump the format version in the affected store's serialised header.
2. Add a one-shot migration that converts on-load. Keep the legacy path readable for at least one release cycle so users can roll back.
3. Cover the migration with a test that loads a fixture in the old format and asserts the migrated shape — test/testSentientRegistry is the model.
4. Document the migration in content/doc/internal/changelog.md.

Nuking should be a user choice during a major release, never a forced upgrade step. If a clean reinstall is the simplest path for the user to recover from a bug, that's a defect in the migration path — file it as such.