Develop Offline Recovery Software That Splits a Secret into Pieces

## Build Recovery Software to Work Years Later for People in Hard Moments Treat recovery software as infrastructure that may remain untouched for years before someone depends on it in a difficult moment. A defect may surface when no maintainer is available, so optimize for durable correctness rather than quick completion. - Understand the existing system before changing it, including why its boundaries and conventions exist. - Match established patterns and standards instead of introducing a locally convenient exception. - Design instructions, messages, and interfaces for people who may be non-technical, overwhelmed, or grieving. - Verify the real outcome, not merely the completion of an assigned edit. Care, empathy, portability, and long-term operability are engineering requirements, not optional polish. ## Find Every Connected Piece Before Changing or Removing a Feature Search before adding any constant, helper, type, list, or source of configuration. Locate the authoritative definition and derive from it so parallel copies cannot drift. - Before changing or removing a feature, trace every connected element across code, styles, translations, types, tests, comments, documentation, and build configuration. - Remove obsolete behavior completely. Do not comment it out, hide it with styling, or leave it behind a condition. - Search again after the change for related identifiers and concepts so leftover references are found intentionally rather than by surprise. - Inspect the final difference for unrelated edits, duplicated logic, dead code, and incomplete cleanup. A feature is not removed until its full dependency and reference graph has been addressed. ## Share One Crypto Core Between the Command Line and the Browser Keep cryptographic operations and other core behavior in a shared implementation used by command-line and browser paths. Thin adapters may differ, but security-sensitive logic, constants, formats, and validation rules should have one source of truth. - Map which runtime owns creation, recovery, packaging, user-interface behavior, and deployment before editing. - Use browser-native code for a lightweight offline recovery path when appropriate, and a compiled browser module for creation when that boundary improves reuse or portability. - Produce offline and network-assisted variants through build-time feature flags so the offline artifact does not include unused network code. - Expose compiled functions through a small, explicit bridge rather than duplicating their behavior in the host language. - Keep runtime and module choices consistent across packages. When embedded assets would create a circular dependency, load the generated module at application initialization and inject its bytes through an explicit interface instead of forcing the cycle. ## Keep Recovery Fully Offline and Use Only Proven Encryption Standalone recovery artifacts must open locally without installation and complete recovery without a server or network connection. Every distributed bundle must remain self-contained and independent of the original repository. - Permit network access only for narrowly documented variants, such as a time-release artifact that briefly checks an external beacon or a self-hosted page that fetches its archive from the same server. - Keep each standalone recipient artifact fully offline even when an optional server variant exists. - Ensure that fewer than the required threshold of key pieces reveals no information about the secret, including through added metadata. - Use established encryption, threshold secret sharing, and time-lock constructions; never invent custom cryptographic primitives. - Keep any time-lock layer inside the primary encryption layer as defense in depth. - Require tests, review, and a clear rationale for every cryptographic change. Do not add telemetry, analytics, remote fonts, content-delivery dependencies, or other hidden network requirements to the recovery path. ## Keep Bundle Formats Stable and Embed Everything Needed to Recover Treat the bundle layout, encrypted payload format, key-piece encoding, and recovery steps as protocol surfaces. Changing them requires migration planning, updated fixtures, compatibility tests, and a documented reason. - Make the recovery experience work across platforms, browsers, and languages. - Embed scripts, styles, templates, and other required assets instead of relying on external services or ephemeral formats. - Include clear text and printable instructions, the encrypted archive metadata, and a personalized recovery page in each recipient bundle. - When the encrypted manifest is 10 MB or smaller, embed it in the personalized page so recovery can work without a separate file; honor an explicit option that disables embedding. - Let browser-based creation embed qualifying manifests automatically when that path has no separate override. - Avoid runtime dependencies on development toolchains for the people who create or recover bundles. Do not promise revocation after key pieces have been distributed, and do not claim the system is guaranteed to work forever. Aim for durability without overstating certainty. ## Write a Failing Test First and Add Browser Tests for Page Changes Write a failing test first, observe the failure, then make it pass. A test that was never seen failing may not exercise the intended behavior. - Add a browser-level test for every change that affects a browser recovery or creation page. - Use focused unit and integration tests for core logic, archive handling, configuration, and command behavior. - Run end-to-end browser tests when changing HTML structure, browser code, layout-affecting styles, visibility, or compiled browser bindings. - Do not require slow browser tests for translation-only edits, documentation changes, copy adjustments, or backend-only changes that cannot affect browser behavior. - Run the relevant tests yourself before reporting completion; do not leave verification to someone else. After any change, search for related terms, rebuild the affected artifacts, run the appropriate tests, and inspect the result. ## Use the Repository's Build and Test Commands Instead of Ad Hoc Tools Understand the complete build pipeline from frontend compilation through browser modules and the final command-line binary. Generated scripts and compiled modules may be embedded into later stages, so command ordering is part of correctness. - Use the repository's canonical build, test, lint, static-site, and development-server commands. - Use the project test wrapper instead of invoking the language test runner directly when generated assets must exist before compilation or embedding. - Run the narrower documented command for a single test only when its prerequisites have already been produced. - Reserve network-dependent test suites for changes that require those integrations. - If a dependency or build tool is unavailable, enter the repository's declared reproducible development environment rather than substituting an ad hoc package runner. Build static artifacts from embedded sources, and keep private recovery artifacts out of public-site deployment unless the release design explicitly includes them. ## Write Calm, Clear Text for People Facing a Stressful Task Write user-facing copy as if every word was chosen for a person facing a consequential and stressful task. Kindness should come from clarity, pacing, and anticipation rather than performed reassurance. - Prefer direct human language over technical phrasing: describe the next action without making the reader decode the implementation. - Address people directly and avoid passive instructions when a clear active sentence is possible. - Use consistent audience-aware terms. In outward-facing copy, prefer “people you trust” and “pieces”; in instructions addressed to recipients, relational terms such as “friends” may be appropriate. - Avoid exclamation marks, filler words, grand claims, mechanical phrasing, and forced enthusiasm. - Use spaced em dashes rather than double hyphens or unspaced dashes. - Keep status messages concise but human, and let success be quiet rather than silent. Favor a soft, warm, non-corporate visual language with restrained contrast. Centralize palette values, avoid pure black, bright red, and corporate blue, and keep any deliberate visual exception isolated and documented. ## Update Docs and Write Changelogs Around What Users Notice When behavior changes, update the relevant documentation, contributor guidance, and operational instructions in the same change. Architecture notes must explain runtime boundaries, generated assets, network exceptions, and the commands required to reproduce results. - Keep configuration and build instructions synchronized with the implementation. - Update fixtures and migration guidance when a stable format changes. - Write changelog entries around what changed for the person using the software. - Lead with the user-facing outcome and include only enough implementation context to make it understandable. - Omit internal refactors and code reorganization unless they change observable behavior. Read nearby entries before writing a new one so the voice and level of detail remain consistent. ## Let the Contributor Review and Submit Changes to the Code Host Themselves Before any action that writes to an external issue tracker or code-hosting service, read the project's contribution policy. When that policy requires human ownership, stop before posting and explain that the contributor is responsible for every line of code and prose. - Show the proposed difference, commit message, or submission description for human review. - Ask the contributor to edit the material in their own words, complete attestations honestly, and perform the commit, push, and submission themselves. - Remove generated footers, co-author lines, filler, and automated attribution before submission. - Do not perform the external write unless the contributor explicitly insists after the ownership requirement has been explained. - If they still insist, keep the message concise and direct, add no automated attribution, and repeat the human-review requirement once. Local editing assistance and read-only inspection do not activate these external-write restrictions. Release automation should still run builds, tests, linting, browser checks, cross-platform packaging, checksums, and representative artifacts before publication.