update

2025-09-10 00:09:04 +00:00 · 2025-07-10 19:37:30 -04:00
parent de5be5f09b
commit 40d16101e0
38 changed files with 11003 additions and 13 deletions
--- a/docs/docs/config.yaml
+++ b/docs/docs/config.yaml
@@ -0,0 +1,13 @@
+site:
+  title: "Archivox Docs"
+  description: "Simple static docs."
+
+navigation:
+  search: true
+
+footer:
+  links:
+    - text: "Custom Link 1"
+      url: "https://example.com"
+    - text: "Custom Link 2"
+      url: "https://example.com/other"
--- a/docs/docs/content/01-getting-started/01-advanced_cli.md
+++ b/docs/docs/content/01-getting-started/01-advanced_cli.md
@@ -0,0 +1,212 @@
+# SeedPass Advanced CLI and API Documentation
+
+## Overview
+
+Welcome to the **Advanced CLI and API Documentation** for **SeedPass**, a secure, deterministic password manager built on Bitcoin's BIP‑85 standard. This guide is designed for power users, developers, and system administrators who wish to leverage the full capabilities of SeedPass through the command line for scripting, automation, and integration.
+
+SeedPass uses a `noun-verb` command structure (e.g., `seedpass entry get <query>`) for a clear, scalable, and discoverable interface. You can explore the available actions for any command group with the `--help` flag (for example, `seedpass entry --help`).
+
+The commands in this document reflect the Typer-based CLI shipped with SeedPass. Each command accepts the optional `--fingerprint` flag to operate on a specific seed profile.
+
+---
+
+## Table of Contents
+
+1. [Global Options](#global-options)
+2. [Command Group Reference](#command-group-reference)
+   - [Entry Commands](#entry-commands)
+   - [Vault Commands](#vault-commands)
+   - [Nostr Commands](#nostr-commands)
+   - [Config Commands](#config-commands)
+   - [Fingerprint Commands](#fingerprint-commands)
+   - [Utility Commands](#utility-commands)
+   - [API Commands](#api-commands)
+3. [Detailed Command Descriptions](#detailed-command-descriptions)
+4. [API Integration](#api-integration)
+5. [Usage Guidelines](#usage-guidelines)
+
+---
+
+## Global Options
+
+These options can be used with any command.
+
+| Flag | Description |
+| :--- | :--- |
+| `--fingerprint <fp>` | Specify which seed profile to use. If omitted, the most recently used profile is selected. |
+| `--help`, `-h` | Display help information for a command or subcommand. |
+
+---
+
+## Command Group Reference
+
+### Entry Commands
+
+Manage individual entries within a vault.
+
+| Action | Command | Examples |
+| :--- | :--- | :--- |
+| List entries | `entry list` | `seedpass entry list --sort label` |
+| Search for entries | `entry search` | `seedpass entry search "GitHub"` |
+| Retrieve an entry's secret (password or TOTP code) | `entry get` | `seedpass entry get "GitHub"` |
+| Add a password entry | `entry add` | `seedpass entry add Example --length 16` |
+| Add a TOTP entry | `entry add-totp` | `seedpass entry add-totp Email --secret JBSW...` |
+| Add an SSH key entry | `entry add-ssh` | `seedpass entry add-ssh Server --index 0` |
+| Add a PGP key entry | `entry add-pgp` | `seedpass entry add-pgp Personal --user-id me@example.com` |
+| Add a Nostr key entry | `entry add-nostr` | `seedpass entry add-nostr Chat` |
+| Add a seed phrase entry | `entry add-seed` | `seedpass entry add-seed Backup --words 24` |
+| Add a key/value entry | `entry add-key-value` | `seedpass entry add-key-value "API Token" --value abc123` |
+| Add a managed account entry | `entry add-managed-account` | `seedpass entry add-managed-account Trading` |
+| Modify an entry | `entry modify` | `seedpass entry modify 1 --username alice` |
+| Archive an entry | `entry archive` | `seedpass entry archive 1` |
+| Unarchive an entry | `entry unarchive` | `seedpass entry unarchive 1` |
+| Export all TOTP secrets | `entry export-totp` | `seedpass entry export-totp --file totp.json` |
+| Show all TOTP codes | `entry totp-codes` | `seedpass entry totp-codes` |
+
+### Vault Commands
+
+Manage the entire vault for a profile.
+
+| Action | Command | Examples |
+| :--- | :--- | :--- |
+| Export the vault | `vault export` | `seedpass vault export --file backup.json` |
+| Import a vault | `vault import` | `seedpass vault import --file backup.json` |
+| Change the master password | `vault change-password` | `seedpass vault change-password` |
+| Lock the vault | `vault lock` | `seedpass vault lock` |
+| Show profile statistics | `vault stats` | `seedpass vault stats` |
+| Reveal or back up the parent seed | `vault reveal-parent-seed` | `seedpass vault reveal-parent-seed --file backup.enc` |
+
+### Nostr Commands
+
+Interact with the Nostr network for backup and synchronization.
+
+| Action | Command | Examples |
+| :--- | :--- | :--- |
+| Sync with relays | `nostr sync` | `seedpass nostr sync` |
+| Get public key | `nostr get-pubkey` | `seedpass nostr get-pubkey` |
+
+### Config Commands
+
+Manage profile‑specific settings.
+
+| Action | Command | Examples |
+| :--- | :--- | :--- |
+| Get a setting value | `config get` | `seedpass config get inactivity_timeout` |
+| Set a setting value | `config set` | `seedpass config set inactivity_timeout 300` |
+
+### Fingerprint Commands
+
+Manage seed profiles (fingerprints).
+
+| Action | Command | Examples |
+| :--- | :--- | :--- |
+| List all profiles | `fingerprint list` | `seedpass fingerprint list` |
+| Add a profile | `fingerprint add` | `seedpass fingerprint add` |
+| Remove a profile | `fingerprint remove` | `seedpass fingerprint remove <fp>` |
+| Switch profile | `fingerprint switch` | `seedpass fingerprint switch <fp>` |
+
+### Utility Commands
+
+Miscellaneous helper commands.
+
+| Action | Command | Examples |
+| :--- | :--- | :--- |
+| Generate a password | `util generate-password` | `seedpass util generate-password --length 24` |
+| Verify script checksum | `util verify-checksum` | `seedpass util verify-checksum` |
+| Update script checksum | `util update-checksum` | `seedpass util update-checksum` |
+
+### API Commands
+
+Run or stop the local HTTP API.
+
+| Action | Command | Examples |
+| :--- | :--- | :--- |
+| Start the API | `api start` | `seedpass api start --host 0.0.0.0 --port 8000` |
+| Stop the API | `api stop` | `seedpass api stop` |
+
+---
+
+## Detailed Command Descriptions
+
+### `entry` Commands
+
+- **`seedpass entry list`** – List entries in the vault, optionally sorted or filtered.
+- **`seedpass entry search <query>`** – Search across labels, usernames, URLs and notes.
+- **`seedpass entry get <query>`** – Retrieve the password or TOTP code for one matching entry, depending on the entry's type.
+- **`seedpass entry add <label>`** – Create a new password entry. Use `--length` to set the password length and optional `--username`/`--url` values.
+- **`seedpass entry add-totp <label>`** – Create a TOTP entry. Use `--secret` to import an existing secret or `--index` to derive from the seed.
+- **`seedpass entry add-ssh <label>`** – Create an SSH key entry derived from the seed.
+- **`seedpass entry add-pgp <label>`** – Create a PGP key entry. Provide `--user-id` and `--key-type` as needed.
+- **`seedpass entry add-nostr <label>`** – Create a Nostr key entry for decentralised chat.
+- **`seedpass entry add-seed <label>`** – Store a derived seed phrase. Use `--words` to set the word count.
+- **`seedpass entry add-key-value <label>`** – Store arbitrary data with `--value`.
+- **`seedpass entry add-managed-account <label>`** – Store a BIP‑85 derived account seed.
+- **`seedpass entry modify <id>`** – Update an entry's label, username, URL or notes.
+- **`seedpass entry archive <id>`** – Mark an entry as archived so it is hidden from normal lists.
+- **`seedpass entry unarchive <id>`** – Restore an archived entry.
+- **`seedpass entry export-totp --file <path>`** – Export all stored TOTP secrets to a JSON file.
+- **`seedpass entry totp-codes`** – Display all current TOTP codes with remaining time.
+
+Example retrieving a TOTP code:
+
+```bash
+$ seedpass entry get "email"
+[##########----------] 15s
+Code: 123456
+```
+
+### `vault` Commands
+
+- **`seedpass vault export`** – Export the entire vault to an encrypted JSON file.
+- **`seedpass vault import`** – Import a vault from an encrypted JSON file.
+- **`seedpass vault change-password`** – Change the master password used for encryption.
+- **`seedpass vault lock`** – Clear sensitive data from memory and require reauthentication.
+- **`seedpass vault stats`** – Display statistics about the active seed profile.
+- **`seedpass vault reveal-parent-seed`** – Print the parent seed or write an encrypted backup with `--file`.
+
+### `nostr` Commands
+
+- **`seedpass nostr sync`** – Perform a two‑way sync with configured Nostr relays.
+- **`seedpass nostr get-pubkey`** – Display the Nostr public key for the active profile.
+
+### `config` Commands
+
+- **`seedpass config get <key>`** – Retrieve a configuration value such as `inactivity_timeout`, `secret_mode`, or `auto_sync`.
+- **`seedpass config set <key> <value>`** – Update a configuration option. Example: `seedpass config set inactivity_timeout 300`.
+- **`seedpass config toggle-secret-mode`** – Interactively enable or disable Secret Mode and set the clipboard delay.
+
+### `fingerprint` Commands
+
+- **`seedpass fingerprint list`** – List available profiles by fingerprint.
+- **`seedpass fingerprint add`** – Create a new seed profile.
+- **`seedpass fingerprint remove <fp>`** – Delete the specified profile.
+- **`seedpass fingerprint switch <fp>`** – Switch the active profile.
+
+### `util` Commands
+
+- **`seedpass util generate-password`** – Generate a strong password of the requested length.
+- **`seedpass util verify-checksum`** – Verify the SeedPass script checksum.
+- **`seedpass util update-checksum`** – Regenerate the script checksum file.
+
+---
+
+## API Integration
+
+SeedPass provides a small REST API for automation. Run `seedpass api start` to launch the server. The command prints a one‑time token which clients must include in the `Authorization` header.
+
+Set the `SEEDPASS_CORS_ORIGINS` environment variable to a comma‑separated list of allowed origins when you need cross‑origin requests:
+
+```bash
+SEEDPASS_CORS_ORIGINS=http://localhost:3000 seedpass api start
+```
+
+Shut down the server with `seedpass api stop`.
+
+---
+
+## Usage Guidelines
+
+- Use the `--help` flag for details on any command.
+- Set a strong master password and regularly export encrypted backups.
+- Adjust configuration values like `inactivity_timeout` or `secret_mode` through the `config` commands.
+- `entry get` is script‑friendly and can be piped into other commands.
--- a/docs/docs/content/01-getting-started/02-api_reference.md
+++ b/docs/docs/content/01-getting-started/02-api_reference.md
@@ -0,0 +1,242 @@
+# SeedPass REST API Reference
+
+This guide covers how to start the SeedPass API, authenticate requests, and interact with the available endpoints.
+
+## Starting the API
+
+Run `seedpass api start` from your terminal. The command prints a one‑time token used for authentication:
+
+```bash
+$ seedpass api start
+API token: abcdef1234567890
+```
+
+Keep this token secret. Every request must include it in the `Authorization` header using the `Bearer` scheme.
+
+## Endpoints
+
+- `GET /api/v1/entry?query=<text>` – Search entries matching a query.
+- `GET /api/v1/entry/{id}` – Retrieve a single entry by its index.
+- `POST /api/v1/entry` – Create a new entry of any supported type.
+- `PUT /api/v1/entry/{id}` – Modify an existing entry.
+- `PUT /api/v1/config/{key}` – Update a configuration value.
+- `POST /api/v1/secret-mode` – Enable or disable Secret Mode and set the clipboard delay.
+- `POST /api/v1/entry/{id}/archive` – Archive an entry.
+- `POST /api/v1/entry/{id}/unarchive` – Unarchive an entry.
+- `GET /api/v1/config/{key}` – Return the value for a configuration key.
+- `GET /api/v1/fingerprint` – List available seed fingerprints.
+- `POST /api/v1/fingerprint` – Add a new seed fingerprint.
+- `DELETE /api/v1/fingerprint/{fp}` – Remove a fingerprint.
+- `POST /api/v1/fingerprint/select` – Switch the active fingerprint.
+- `GET /api/v1/totp/export` – Export all TOTP entries as JSON.
+- `GET /api/v1/totp` – Return current TOTP codes and remaining time.
+- `GET /api/v1/stats` – Return statistics about the active seed profile.
+- `GET /api/v1/parent-seed` – Reveal the parent seed or save it with `?file=`.
+- `GET /api/v1/nostr/pubkey` – Fetch the Nostr public key for the active seed.
+- `POST /api/v1/checksum/verify` – Verify the checksum of the running script.
+- `POST /api/v1/checksum/update` – Update the stored script checksum.
+- `POST /api/v1/change-password` – Change the master password for the active profile.
+- `POST /api/v1/vault/import` – Import a vault backup from a file or path.
+- `POST /api/v1/vault/export` – Export the vault and download the encrypted file.
+- `POST /api/v1/vault/backup-parent-seed` – Save an encrypted backup of the parent seed.
+- `POST /api/v1/vault/lock` – Lock the vault and clear sensitive data from memory.
+- `GET /api/v1/relays` – List configured Nostr relays.
+- `POST /api/v1/relays` – Add a relay URL.
+- `DELETE /api/v1/relays/{idx}` – Remove the relay at the given index (1‑based).
+- `POST /api/v1/relays/reset` – Reset the relay list to defaults.
+- `POST /api/v1/shutdown` – Stop the server gracefully.
+
+**Security Warning:** Accessing `/api/v1/parent-seed` exposes your master seed in plain text. Use it only from a trusted environment.
+
+## Example Requests
+
+Send requests with the token in the header:
+
+```bash
+curl -H "Authorization: Bearer <token>" \
+     "http://127.0.0.1:8000/api/v1/entry?query=email"
+```
+
+### Creating an Entry
+
+`POST /api/v1/entry` accepts a JSON body with at least a `label` field. Set
+`type` (or `kind`) to choose the entry variant (`password`, `totp`, `ssh`, `pgp`,
+`nostr`, `seed`, `key_value`, or `managed_account`). Additional fields vary by
+type:
+
+- **password** – `length`, optional `username`, `url` and `notes`
+- **totp** – `secret` or `index`, optional `period`, `digits`, `notes`, `archived`
+- **ssh/nostr/seed/managed_account** – `index`, optional `notes`, `archived`
+- **pgp** – `index`, `key_type`, `user_id`, optional `notes`, `archived`
+- **key_value** – `value`, optional `notes`
+
+Example creating a TOTP entry:
+
+```bash
+curl -X POST http://127.0.0.1:8000/api/v1/entry \
+     -H "Authorization: Bearer <token>" \
+     -H "Content-Type: application/json" \
+     -d '{"type": "totp", "label": "Email", "secret": "JBSW..."}'
+```
+
+### Updating an Entry
+
+Use `PUT /api/v1/entry/{id}` to change fields such as `label`, `username`,
+`url`, `notes`, `period`, `digits` or `value` depending on the entry type.
+
+```bash
+curl -X PUT http://127.0.0.1:8000/api/v1/entry/1 \
+     -H "Authorization: Bearer <token>" \
+     -H "Content-Type: application/json" \
+     -d '{"username": "alice"}'
+```
+
+### Updating Configuration
+
+Send a JSON body containing a `value` field to `PUT /api/v1/config/{key}`:
+
+```bash
+curl -X PUT http://127.0.0.1:8000/api/v1/config/inactivity_timeout \
+     -H "Authorization: Bearer <token>" \
+     -H "Content-Type: application/json" \
+     -d '{"value": 300}'
+```
+
+### Toggling Secret Mode
+
+Send both `enabled` and `delay` values to `/api/v1/secret-mode`:
+
+```bash
+curl -X POST http://127.0.0.1:8000/api/v1/secret-mode \
+     -H "Authorization: Bearer <token>" \
+     -H "Content-Type: application/json" \
+     -d '{"enabled": true, "delay": 20}'
+```
+
+### Switching Fingerprints
+
+Change the active seed profile via `POST /api/v1/fingerprint/select`:
+
+```bash
+curl -X POST http://127.0.0.1:8000/api/v1/fingerprint/select \
+     -H "Authorization: Bearer <token>" \
+     -H "Content-Type: application/json" \
+    -d '{"fingerprint": "abc123"}'
+```
+
+### Exporting the Vault
+
+Download an encrypted vault backup via `POST /api/v1/vault/export`:
+
+```bash
+curl -X POST http://127.0.0.1:8000/api/v1/vault/export \
+     -H "Authorization: Bearer <token>" \
+     -o backup.json
+```
+
+### Importing a Vault
+
+Restore a backup with `POST /api/v1/vault/import`. Use `-F` to upload a file:
+
+```bash
+curl -X POST http://127.0.0.1:8000/api/v1/vault/import \
+     -H "Authorization: Bearer <token>" \
+     -F file=@backup.json
+```
+
+### Locking the Vault
+
+Clear sensitive data from memory using `/api/v1/vault/lock`:
+
+```bash
+curl -X POST http://127.0.0.1:8000/api/v1/vault/lock \
+     -H "Authorization: Bearer <token>"
+```
+
+### Backing Up the Parent Seed
+
+Trigger an encrypted seed backup with `/api/v1/vault/backup-parent-seed`:
+
+```bash
+curl -X POST http://127.0.0.1:8000/api/v1/vault/backup-parent-seed \
+     -H "Authorization: Bearer <token>" \
+     -H "Content-Type: application/json" \
+     -d '{"path": "seed_backup.enc"}'
+```
+
+### Retrieving Vault Statistics
+
+Get profile stats such as entry counts with `GET /api/v1/stats`:
+
+```bash
+curl -H "Authorization: Bearer <token>" \
+     http://127.0.0.1:8000/api/v1/stats
+```
+
+### Changing the Master Password
+
+Update the vault password via `POST /api/v1/change-password`:
+
+```bash
+curl -X POST http://127.0.0.1:8000/api/v1/change-password \
+     -H "Authorization: Bearer <token>"
+```
+
+### Verifying the Script Checksum
+
+Check that the running script matches the stored checksum:
+
+```bash
+curl -X POST http://127.0.0.1:8000/api/v1/checksum/verify \
+     -H "Authorization: Bearer <token>"
+```
+
+### Updating the Script Checksum
+
+Regenerate the stored checksum using `/api/v1/checksum/update`:
+
+```bash
+curl -X POST http://127.0.0.1:8000/api/v1/checksum/update \
+     -H "Authorization: Bearer <token>"
+```
+
+### Managing Relays
+
+List, add, or remove Nostr relays:
+
+```bash
+# list
+curl -H "Authorization: Bearer <token>" http://127.0.0.1:8000/api/v1/relays
+
+# add
+curl -X POST http://127.0.0.1:8000/api/v1/relays \
+     -H "Authorization: Bearer <token>" \
+     -H "Content-Type: application/json" \
+     -d '{"url": "wss://relay.example.com"}'
+
+# remove first relay
+curl -X DELETE http://127.0.0.1:8000/api/v1/relays/1 \
+     -H "Authorization: Bearer <token>"
+
+# reset to defaults
+curl -X POST http://127.0.0.1:8000/api/v1/relays/reset \
+     -H "Authorization: Bearer <token>"
+```
+
+### Enabling CORS
+
+Cross‑origin requests are disabled by default. Set `SEEDPASS_CORS_ORIGINS` to a comma‑separated list of allowed origins before starting the API:
+
+```bash
+SEEDPASS_CORS_ORIGINS=http://localhost:3000 seedpass api start
+```
+
+Browsers can then call the API from the specified origins, for example using JavaScript:
+
+```javascript
+fetch('http://127.0.0.1:8000/api/v1/entry?query=email', {
+  headers: { Authorization: 'Bearer <token>' }
+});
+```
+
+Without CORS enabled, only same‑origin or command‑line tools like `curl` can access the API.
--- a/docs/docs/content/01-getting-started/03-json_entries.md
+++ b/docs/docs/content/01-getting-started/03-json_entries.md
@@ -0,0 +1,573 @@
+# SeedPass JSON Entry Management and Extensibility
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [JSON Schema for Individual Entries](#json-schema-for-individual-entries)
+  - [General Structure](#general-structure)
+  - [Field Descriptions](#field-descriptions)
+  - [Example Entries](#example-entries)
+- [Handling `kind` Types and Extensibility](#handling-kind-types-and-extensibility)
+  - [Extensible JSON Schema Design](#extensible-json-schema-design)
+  - [Ensuring Backward Compatibility](#ensuring-backward-compatibility)
+  - [Best Practices for Adding New Kinds](#best-practices-for-adding-new-kinds)
+- [Adding New `kind` Types](#adding-new-kind-types)
+  - [Example: Adding `cryptocurrency_wallet`](#example-adding-cryptocurrency_wallet)
+- [Backup and Rollback Mechanism](#backup-and-rollback-mechanism)
+- [Security Considerations](#security-considerations)
+- [Updated Roadmap](#updated-roadmap)
+  - [Phase 1: Core Functionality and Security Enhancements](#phase-1-core-functionality-and-security-enhancements)
+  - [Phase 2: Enhanced Security and Data Management](#phase-2-enhanced-security-and-data-management)
+  - [Phase 3: Advanced CLI Functionalities](#phase-3-advanced-cli-functionalities)
+  - [Phase 4: Data Management Enhancements and Integrations](#phase-4-data-management-enhancements-and-integrations)
+  - [Phase 5: Documentation, Testing, and Finalization](#phase-5-documentation-testing-and-finalization)
+  - [Future Phases (Beyond Initial Roadmap)](#future-phases-beyond-initial-roadmap)
+- [Summary](#summary)
+- [Contact](#contact)
+
+---
+
+## Introduction
+
+**SeedPass** is a secure password generator and manager leveraging **Bitcoin's BIP-85 standard** and integrating with the **Nostr network** for decentralized synchronization. Instead of pushing one large index file, SeedPass posts **snapshot chunks** of the index followed by lightweight **delta events** whenever changes occur. This chunked approach improves reliability and keeps bandwidth usage minimal. To enhance modularity, scalability, and security, SeedPass stores all entries in a single encrypted index file named `seedpass_entries_db.json.enc`. This document outlines the entry management system, ensuring that new `kind` types can be added seamlessly without disrupting existing functionalities.
+
+---
+
+## Index File Format
+
+All entries belonging to a seed profile are stored in an encrypted file named `seedpass_entries_db.json.enc`. This index uses `schema_version` `3` and contains an `entries` object keyed by numeric identifiers.
+
+```json
+{
+  "schema_version": 3,
+  "entries": {
+    "0": {
+      "label": "example.com",
+      "length": 8,
+      "username": "user",
+      "url": "https://example.com",
+      "archived": false,
+      "type": "password",
+      "kind": "password",
+      "notes": "",
+      "custom_fields": [],
+      "origin": ""
+    }
+  }
+}
+```
+
+---
+
+## JSON Schema for Individual Entries
+
+Each entry is stored within `seedpass_entries_db.json.enc` under the `entries` dictionary. The structure supports diverse entry types (`kind`) and allows for future expansions.
+
+### General Structure
+
+```json
+{
+  "label": "Example",
+  "length": 8,
+  "username": "user@example.com",
+  "url": "https://example.com",
+  "archived": false,
+  "type": "password",
+  "kind": "password",
+  "notes": "",
+  "custom_fields": [],
+  "origin": "",
+  "tags": [],
+  "index": 0
+}
+```
+
+### Field Descriptions
+
+- **label** (`string`): Descriptive name for the entry (e.g., website or service).
+- **length** (`integer`, optional): Desired password length for generated passwords.
+- **username** (`string`, optional): Username associated with the entry.
+- **url** (`string`, optional): Website or service URL.
+- **archived** (`boolean`): Marks the entry as archived when `true`.
+- **type** (`string`): The entry type (`password`, `totp`, `ssh`, `seed`, `pgp`, `nostr`, `note`, `key_value`).
+- **kind** (`string`): Synonym for `type` kept for backward compatibility.
+- **notes** (`string`): Free-form notes.
+- **custom_fields** (`array`, optional): Additional user-defined fields.
+- **origin** (`string`, optional): Source identifier for imported data.
+- **value** (`string`, optional): For `key_value` entries, stores the secret value.
+- **index** (`integer`, optional): BIP-85 derivation index for entries that derive material from a seed.
+- **word_count** (`integer`, managed_account only): Number of words in the child seed. Managed accounts always use `12`.
+- **fingerprint** (`string`, managed_account only): Identifier of the child profile, used for its directory name.
+- **tags** (`array`, optional): Category labels to aid in organization and search.
+  Example:
+
+  ```json
+  "custom_fields": [
+    {"name": "account_id", "value": "123"},
+    {"name": "recovery_hint", "value": "mother's maiden name"}
+  ]
+  ```
+
+### Example Entries
+
+#### 1. Generated Password
+
+```json
+{
+  "entry_num": 0,
+  "index_num": 0,
+  "fingerprint": "a1b2c3d4",
+  "kind": "generated_password",
+  "data": {
+    "title": "Example Website",
+    "username": "user@example.com",
+    "email": "user@example.com",
+    "url": "https://example.com",
+    "password": "<encrypted_password>"
+  },
+  "custom_fields": [
+    {"name": "department", "value": "finance"}
+  ],
+  "tags": ["work"],
+  "timestamp": "2024-04-27T12:34:56Z",
+  "metadata": {
+    "created_at": "2024-04-27T12:34:56Z",
+    "updated_at": "2024-04-27T12:34:56Z",
+    "checksum": "abc123def456"
+  }
+}
+```
+
+#### 2. Stored Password
+
+```json
+{
+  "entry_num": 1,
+  "index_num": "q1wec4d426fs",
+  "fingerprint": "a1b2c3d4",
+  "kind": "stored_password",
+  "data": {
+    "title": "Another Service",
+    "username": "another_user",
+    "password": "<encrypted_password>"
+  },
+  "timestamp": "2024-04-27T12:35:56Z",
+  "metadata": {
+    "created_at": "2024-04-27T12:35:56Z",
+    "updated_at": "2024-04-27T12:35:56Z",
+    "checksum": "def789ghi012"
+  }
+}
+```
+
+#### 3. Managed User
+
+```json
+{
+  "entry_num": 2,
+  "index_num": "a1b2c3d4e5f6",
+  "fingerprint": "a1b2c3d4",
+  "kind": "managed_user",
+  "data": {
+    "users_password": "<encrypted_users_password>"
+  },
+  "timestamp": "2024-04-27T12:36:56Z",
+  "metadata": {
+    "created_at": "2024-04-27T12:36:56Z",
+    "updated_at": "2024-04-27T12:36:56Z",
+    "checksum": "ghi345jkl678"
+  }
+}
+```
+
+#### 4. 12 Word Seed
+
+```json
+{
+  "entry_num": 3,
+  "index_num": "f7g8h9i0j1k2",
+  "fingerprint": "a1b2c3d4",
+  "kind": "12_word_seed",
+  "data": {
+    "seed_phrase": "<encrypted_seed_phrase>"
+  },
+  "timestamp": "2024-04-27T12:37:56Z",
+  "metadata": {
+    "created_at": "2024-04-27T12:37:56Z",
+    "updated_at": "2024-04-27T12:37:56Z",
+    "checksum": "jkl901mno234"
+  }
+}
+```
+
+#### 5. Nostr Keys
+
+```json
+{
+  "entry_num": 4,
+  "index_num": "l3m4n5o6p7q8",
+  "fingerprint": "a1b2c3d4",
+  "kind": "nostr_keys",
+  "data": {
+    "public_key": "<public_key>",
+    "private_key": "<encrypted_private_key>"
+  },
+  "timestamp": "2024-04-27T12:38:56Z",
+  "metadata": {
+    "created_at": "2024-04-27T12:38:56Z",
+    "updated_at": "2024-04-27T12:38:56Z",
+    "checksum": "mno567pqr890"
+  }
+}
+```
+
+#### 6. Note
+
+```json
+{
+  "entry_num": 5,
+  "index_num": "r9s0t1u2v3w4",
+  "fingerprint": "a1b2c3d4",
+  "kind": "note",
+  "data": {
+    "content": "This is a secure note.",
+    "tags": ["personal", "secure"]
+  },
+  "timestamp": "2024-04-27T12:39:56Z",
+  "metadata": {
+    "created_at": "2024-04-27T12:39:56Z",
+    "updated_at": "2024-04-27T12:39:56Z",
+    "checksum": "pqr345stu678"
+  }
+}
+```
+
+#### 7. Key/Value
+
+```json
+{
+  "entry_num": 6,
+  "fingerprint": "a1b2c3d4",
+  "kind": "key_value",
+  "data": {
+    "key": "api_key",
+    "value": "<encrypted_value>"
+  },
+  "tags": ["api"],
+  "timestamp": "2024-04-27T12:40:56Z"
+}
+```
+
+#### 8. Managed Account
+
+```json
+{
+  "entry_num": 7,
+  "fingerprint": "a1b2c3d4",
+  "kind": "managed_account",
+  "data": {
+    "account": "alice@example.com",
+    "password": "<encrypted_password>"
+  },
+  "timestamp": "2024-04-27T12:41:56Z"
+}
+```
+
+Managed accounts store a child seed derived from the parent profile. The entry is saved under
+`.seedpass/<parent_fp>/accounts/<child_fp>` where `<child_fp>` is the managed account's
+fingerprint. When loaded, the CLI displays a breadcrumb like `<parent_fp> > Managed Account > <child_fp>`.
+Press **Enter** on the main menu to exit back to the parent profile.
+
+The `key` field is purely descriptive, while `value` holds the sensitive string
+such as an API token. Notes and custom fields may also be included alongside the
+standard metadata.
+
+---
+
+## Handling `kind` Types and Extensibility
+
+### Extensible JSON Schema Design
+
+The JSON schema is designed to be **extensible** and **forward-compatible**, allowing new `kind` types to be added without impacting existing functionalities.
+
+#### a. Core Structure
+
+Each entry is encapsulated in its own JSON file with a standardized structure:
+
+```json
+{
+  "entry_num": 0,
+  "index_num": 0,
+  "fingerprint": "a1b2c3d4",
+  "kind": "generated_password",
+  "data": {
+    // Fields specific to the kind
+  },
+  "timestamp": "2024-04-27T12:34:56Z",
+  "metadata": {
+    "created_at": "2024-04-27T12:34:56Z",
+    "updated_at": "2024-04-27T12:34:56Z",
+    "checksum": "<checksum_value>"
+  }
+}
+```
+
+#### b. The `kind` Field
+
+- **Purpose:** Specifies the type of entry.
+- **Flexibility:** As a simple string identifier, new `kind` values can be introduced without altering the existing schema.
+
+**Example:**
+```json
+"kind": "cryptocurrency_wallet"
+```
+
+#### c. The `data` Object
+
+- **Purpose:** Contains fields specific to the `kind`.
+- **Extensibility:** Each `kind` can define its unique set of fields without affecting others.
+
+**Example for a New Kind (`cryptocurrency_wallet`):**
+```json
+"data": {
+  "wallet_name": "My Bitcoin Wallet",
+  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
+  "private_key": "<encrypted_private_key>"
+}
+```
+
+### Ensuring Backward Compatibility
+
+To maintain compatibility as new `kind` types are introduced, implement the following practices:
+
+#### a. Graceful Handling of Unknown Kinds
+
+- **Implementation:** When encountering an unrecognized `kind`, handle it gracefully by ignoring the entry, logging a warning, or providing a default handling mechanism.
+- **Benefit:** Prevents the application from crashing or misbehaving due to unrecognized `kind` types.
+
+**Pseudo-Code Example:**
+```python
+def process_entry(entry):
+    kind = entry.get("kind")
+    data = entry.get("data")
+    fingerprint = entry.get("fingerprint")
+    
+    if kind == "generated_password":
+        handle_generated_password(data, fingerprint)
+    elif kind == "stored_password":
+        handle_stored_password(data, fingerprint)
+    # ... other known kinds ...
+    else:
+        log_warning(f"Unknown kind: {kind}. Skipping entry.")
+```
+
+#### b. Versioning the Schema
+
+- **Implementation:** Introduce a `schema_version` or `seedpass_version` field to indicate the version of the JSON schema being used.
+- **Benefit:** Facilitates future updates and migrations by clearly identifying the schema version.
+
+**Example:**
+```json
+"seedpass_version": "1.0.0"
+```
+
+#### c. Documentation and Standards
+
+- **Maintain Clear Documentation:** Keep comprehensive documentation for each `kind`, detailing required and optional fields.
+- **Adhere to Standards:** Follow consistent naming conventions and data types to ensure uniformity across different `kind` types.
+
+### Best Practices for Adding New Kinds
+
+To ensure seamless integration of new `kind` types in the future, consider the following best practices:
+
+#### a. Consistent Naming Conventions
+
+- **Use Clear and Descriptive Names:** Aids in readability and maintenance.
+- **Avoid Reserved Keywords:** Ensure `kind` names do not clash with existing or future reserved keywords within the application or JSON standards.
+
+#### b. Modular Code Architecture
+
+- **Separate Handlers:** Implement separate functions or modules for handling each `kind`. Promotes code modularity and easier maintenance.
+
+**Example:**
+```python
+# handlers.py
+
+def handle_generated_password(data, fingerprint):
+    # Implementation
+
+def handle_stored_password(data, fingerprint):
+    # Implementation
+
+def handle_cryptocurrency_wallet(data, fingerprint):
+    # Implementation
+```
+
+#### c. Validation and Error Handling
+
+- **Validate Data Fields:** Ensure each `kind` has the necessary fields before processing.
+- **Handle Missing or Extra Fields:** Implement logic to manage incomplete or unexpected data gracefully.
+
+**Example:**
+```python
+def handle_cryptocurrency_wallet(data, fingerprint):
+    required_fields = ["wallet_name", "address", "private_key"]
+    for field in required_fields:
+        if field not in data:
+            raise ValueError(f"Missing required field '{field}' in cryptocurrency_wallet entry.")
+    # Proceed with processing
+```
+
+#### d. Backward Compatibility Testing
+
+- **Automated Tests:** Develop tests that verify the application's ability to handle both existing and new `kind` types.
+- **Regression Testing:** Ensure adding new kinds does not inadvertently affect existing functionalities.
+
+---
+
+## Adding New `kind` Types
+
+Adding new `kind` types is straightforward due to the extensible JSON schema design. Below is a step-by-step guide to adding a new `kind` without affecting existing functionalities.
+
+### Example: Adding `cryptocurrency_wallet`
+
+#### a. Define the New Kind Structure
+
+Create a JSON file following the standardized structure with the new `kind` value.
+
+```json
+{
+  "entry_num": 6,
+  "index_num": "x1y2z3a4b5c6",
+  "fingerprint": "a1b2c3d4",
+  "kind": "cryptocurrency_wallet",
+  "data": {
+    "wallet_name": "My Bitcoin Wallet",
+    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
+    "private_key": "<encrypted_private_key>"
+  },
+  "timestamp": "2024-04-27T12:40:56Z",
+  "metadata": {
+    "created_at": "2024-04-27T12:40:56Z",
+    "updated_at": "2024-04-27T12:40:56Z",
+    "checksum": "stu901vwx234"
+  }
+}
+```
+
+#### b. Update the Application to Handle the New Kind
+
+**Implement Handler Function:**
+```python
+def handle_cryptocurrency_wallet(data, fingerprint):
+    wallet_name = data.get("wallet_name")
+    address = data.get("address")
+    private_key = decrypt(data.get("private_key"))
+    # Process the cryptocurrency wallet entry
+    # e.g., store in memory, display to user, etc.
+```
+
+**Integrate the Handler:**
+```python
+def process_entry(entry):
+    kind = entry.get("kind")
+    data = entry.get("data")
+    fingerprint = entry.get("fingerprint")
+    
+    if kind == "generated_password":
+        handle_generated_password(data, fingerprint)
+    elif kind == "stored_password":
+        handle_stored_password(data, fingerprint)
+    elif kind == "cryptocurrency_wallet":
+        handle_cryptocurrency_wallet(data, fingerprint)
+    # ... other known kinds ...
+    else:
+        log_warning(f"Unknown kind: {kind}. Skipping entry.")
+```
+
+#### c. No Impact on Existing Kinds
+
+Existing kinds such as `generated_password`, `stored_password`, etc., continue to operate without any changes. The introduction of `cryptocurrency_wallet` is additive and does not interfere with the processing of other kinds.
+
+---
+
+## Backup and Rollback Mechanism
+
+To ensure data integrity and provide recovery options, SeedPass implements a robust backup and rollback system within the **Fingerprint-Based Backup and Local Storage** framework.
+
+### Backup Directory Structure
+
+All backups are organized based on fingerprints, ensuring that each seed's data remains isolated and secure.
+
+```
+~/.seedpass/
+├── a1b2c3d4/
+│   ├── entries/
+│   │   ├── entry_0.json
+│   │   ├── entry_1.json
+│   │   └── ...
+│   ├── backups/
+│   │   ├── entry_0_v1.json
+│   │   ├── entry_0_v2.json
+│   │   ├── entry_1_v1.json
+│   │   └── ...
+│   ├── parent_seed.enc
+│   ├── seedpass_entries_db_checksum.txt
+│   └── seedpass_entries_db.json
+├── b5c6d7e8/
+│   ├── entries/
+│   │   ├── entry_0.json
+│   │   ├── entry_1.json
+│   │   └── ...
+│   ├── backups/
+│   │   ├── entry_0_v1.json
+│   │   ├── entry_0_v2.json
+│   │   ├── entry_1_v1.json
+│   │   └── ...
+│   ├── parent_seed.enc
+│   ├── seedpass_entries_db_checksum.txt
+│   └── seedpass_entries_db.json
+└── ...
+```
+
+### Backup Process
+
+1. **Upon Modifying an Entry:**
+   - The current version of the entry is copied to the `backups/` directory within the corresponding fingerprint folder with a version suffix (e.g., `entry_0_v1.json`).
+   - The modified entry is saved in the `entries/` directory within the same fingerprint folder.
+
+2. **Versioning:**
+   - Each backup file includes a version number to track changes over time.
+
+### Rollback Functionality
+
+- **Restoring an Entry:**
+  - Users can select a backup version from the `backups/` directory within the specific fingerprint folder.
+  - The selected backup file is copied back to the `entries/` directory, replacing the current version.
+
+**Example Command:**
+```bash
+seedpass rollback --fingerprint a1b2c3d4 --file entry_0_v1.json
+```
+
+**Example Directory Structure After Rollback:**
+```
+~/.seedpass/
+├── a1b2c3d4/
+│   ├── entries/
+│   │   ├── entry_0.json  # Restored from entry_0_v1.json
+│   │   ├── entry_1.json
+│   │   └── ...
+│   ├── backups/
+│   │   ├── entry_0_v1.json
+│   │   ├── entry_0_v2.json
+│   │   ├── entry_1_v1.json
+│   │   └── ...
+│   ├── parent_seed.enc
+│   ├── seedpass_script_checksum.txt
+│   ├── seedpass_entries_db_checksum.txt
+│   └── seedpass_entries_db.json
+├── ...
+```
+
+*Note: Restoring a backup overwrites the current entry. Ensure that you intend to revert to the selected backup before proceeding.*
--- a/docs/docs/content/01-getting-started/04-migrations.md
+++ b/docs/docs/content/01-getting-started/04-migrations.md
@@ -0,0 +1,25 @@
+# Index Migrations
+
+SeedPass stores its password index in an encrypted JSON file. Each index contains
+a `schema_version` field so the application knows how to upgrade older files.
+
+## How migrations work
+
+When the vault loads the index, `Vault.load_index()` checks the version and
+applies migrations defined in `password_manager/migrations.py`. The
+`apply_migrations()` function iterates through registered migrations until the
+file reaches `LATEST_VERSION`.
+
+If an old file lacks `schema_version`, it is treated as version 0 and upgraded
+to the latest format. Attempting to load an index from a future version will
+raise an error.
+
+## Upgrading an index
+
+1. The JSON is decrypted and parsed.
+2. `apply_migrations()` applies any necessary steps, such as injecting the
+   `schema_version` field on first upgrade.
+3. After migration, the updated index is saved back to disk.
+
+This process happens automatically; users only need to open their vault to
+upgrade older indices.
--- a/docs/docs/content/01-getting-started/index.md
+++ b/docs/docs/content/01-getting-started/index.md
@@ -0,0 +1,3 @@
+# Getting Started
+
+Welcome to SeedPass!
--- a/docs/docs/content/index.md
+++ b/docs/docs/content/index.md
@@ -0,0 +1,15 @@
+# Archivox Documentation
+
+Welcome to the official documentation for **Archivox**, a lightweight static site generator designed for "Read&nbsp;the&nbsp;Docs" style websites.
+
+## Quick Start
+
+```bash
+npm install
+npm run dev # start local server at http://localhost:8080
+npm run build # generate the _site/ folder
+```
+
+Archivox converts Markdown files inside a `content/` folder into a full documentation site with search, navigation, and responsive design.
+
+Check the **Getting Started** section to learn how to run Archivox locally and the **Project Integration** guide to drop Archivox into an existing codebase.
--- a/docs/docs/package.json
+++ b/docs/docs/package.json
@@ -0,0 +1,11 @@
+{
+  "name": "docs",
+  "private": true,
+  "scripts": {
+    "dev": "eleventy --serve",
+    "build": "node node_modules/archivox/src/generator/index.js"
+  },
+  "dependencies": {
+    "archivox": "^1.0.0"
+  }
+}