| name | ark-record |
| description | Record a manual session entry into the developer's workspace journal. Use when the user wants to write down notes between tasks (explorations, observations, status updates). |
ark-record <task description>
Append a manual session entry (not tied to any task) to the developer's active journal under .ark/workspace/<dev>/journal-N.md. Use this for inter-task notes: explorations, investigations, observations.
Task-driven entries are written automatically by ark-commit; do not run ark-record for those.
Preconditions
.ark/.developer exists (run ark init --developer <name> to bootstrap).
Steps
Step 1: Pull record context [AI]
ark context --scope record --format json
Returns resolved identity, active_journal_path, session count, branch, journal_max_lines. Use <task description> as the title or prompt for one if absent.
Step 2: Append the entry [AI]
Append a block to active_journal_path containing exactly three agent-authored sections:
## Session N: <title>
### Summary
<one-line summary>
### Main Changes
| Area | Description |
|------|-------------|
| <area> | <description> |
Do not write **Date**, **Slug**, **Branch** — the CLI inserts those after your ## Session N: heading. Show the user what you wrote.
Step 3: Stamp the auto-fields [AI]
ark agent workspace record --manual
The CLI: resolves identity, locates the active journal-N.md, stamps **Date**, **Slug**: -, **Branch** after your last ## Session N: heading, updates the personal Session History row, refreshes top-level Active Developers. Transactional with rollback.
Failure Modes
| Code | Cause | Recovery |
|---|
MissingIdentity | .ark/.developer not present | Run ark init --developer <name> |
EntryFileMalformed | journal does not end with a ## Session N: <title> heading | Step 2 must place the heading at the very end, no trailing content after the Main Changes table |
JournalDriftDetected | concurrent appender wrote bytes after this transaction | Journal is left intact; investigate manually |
See Also
workflow.md §8 (state & multi-session)ark-commit — task-driven journal entries (do not use ark-record for those)
