Description
HUMAN.md Portability gives users a deliberate round-trip between their durable Dots persona document and ordinary local editing tools. dots human-md export resolves and writes the active persona document, while dots human-md import reads local content and updates the corresponding Dots surface through the authenticated API.
The workflow is designed for operators and coding agents. It uses the same authenticated, company-scoped service contracts as the rest of Dots, so terminal or protocol convenience never creates a second source of truth. Inputs are validated before or at the route boundary, and outputs preserve identifiers and structured details needed for a reliable next step.
Selling Points
- Lets users review and edit their agent-facing persona in familiar local tools.
- Creates a portable backup that can participate in normal file workflows.
- Keeps import and export explicit, avoiding silent background overwrites.
- Uses the canonical active HUMAN.md resolution rather than guessing a row.
- Makes persona maintenance available in headless and remote environments.
User Story
A user exports the active HUMAN.md, revises working preferences in their editor, reviews the diff, and imports the file. The next agent session reads the updated durable persona instead of a transient prompt pasted into one conversation. The result is a concrete, inspectable outcome that another person or automation can continue from without reconstructing hidden state.
Extension Surface
The surface is automatable: packages/cli/src/commands/human-md.ts implements a closed import/export bridge. The document is user-configurable content, but the CLI does not support third-party transport registration. The rating reflects the most-open supported seam that is true for this capability, not a transitive implementation detail. The cited path is the operational proof: consumers can use the documented seam, while unsupported changes still require a core release.
Capabilities & Limits
- Capability: Canonical HUMAN.md export to a local file.
- Capability: Explicit local-file import into the durable platform document.
- Capability: Authenticated company-aware operation with standard CLI errors.
- Limit: This is a manual round-trip, not continuous two-way synchronization; conflicting concurrent edits still require user judgment.
The limit is intentional product truth rather than missing documentation. Calls also remain subject to authentication, tenant selection, schema validation, and the permissions enforced by the authoritative service.
Implementation Map
packages/cli/src/commands/human-md.tspackages/cli/src/program.tsdocs/cli/settings-files-and-human-md-commands.md