mps 0.5.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f0d20f2919cb1ee0ae46a3fe6eaef005af856eabd4650fc5e6e07477b5e7fb3
-  data.tar.gz: 259a623e9ee4b8edea593ab16a270b11015a55e3e22564359a424610f0510caa
+  metadata.gz: 96b0eac30435621ea7ca9d0575d3a3285a074cb2707d453075ced7e1535ca288
+  data.tar.gz: 647d49ad9cffd798858318dd712d4653df718e37d05a8f52803be367e423c17c
 SHA512:
-  metadata.gz: 4653dca542034d736e5e61c69b2750c5ddb119c141876fac896b3f15e79d3d758f9e299a3ecf75fd17c52c5e7dbd8da9a562be228d760c6e4a7ba290359c83b0
-  data.tar.gz: 9cf8bf1273e814ed6708561c1f7cd5b82917e804b0e97e867d34c50bb2f35e762067f3df3493cb59eb4eea3ab0e5b1be9e02c38cbc7fffb43c9b9494c4790be3
+  metadata.gz: e1204e48c493e45f0dc226b1a7a4de0751b4821774ab5984c54f56cf53e91ac99cb09a17fb5cf777de0cf665ebefd69289913de935baf5655d3afd76f80da9bf
+  data.tar.gz: bbb938d0b337b652c07cca9983949a830c13fd9180ab037df87bd75feda68a6e11dfbc091689fa96546edc1e6f5f02e770b98a6d896c32b90de2b95b0fcaae00

data/.github/workflows/main.yml

@@ -1,29 +1,34 @@
-name: Ruby
+name: Ruby CI
 
 on:
   push:
-    branches:
-      - master
-      - release/*
+    branches: [master, "release/*"]
   pull_request:
-    branches:
-      - master
-      - dev
-      - release/*
+    branches: [master, dev, "release/*"]
 
 jobs:
-  build:
+  test:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Futureproofing: Test against multiple versions
+        # This ensures you catch the "RubyGems 4.0" issue before your users do
+        ruby: ["3.1", "3.2", "3.3"]
+
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4 # Use the latest version
+
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 3.0.2
-      - name: Run the default task
-        run: |
-          gem update --system
-          gem install bundler -v 2.2.13
-          bundle add rake
-          bundle install
-          bundle exec rake
+          ruby-version: ${{ matrix.ruby }}
+          # AUTOMATIC FUTUREPROOFING:
+          # This handles 'bundle install' and caching for you efficiently.
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rake
+
+      - name: Run with groups tests
+        run: bundle exec rake test:with_groups

data/.gitignore

@@ -6,8 +6,9 @@
 /pkg/
 /spec/reports/
 /tmp/
-*.lock
 *.mps
+!test/assets/*.mps
 /vendor/
-**/**/*.gem
-
+*.gem
+.claude/
+prompt-for-v1-rollout.txt

data/ARCHITECTURE.md

@@ -0,0 +1,298 @@
+# MPS — Canonical Architecture Document
+
+> Updated for v1.0. Reflects all Phase 1–7 changes.
+> For AI agents and developers evolving the system.
+
+---
+
+## 1. Core Vision and Goals
+
+MPS is a **plain-text personal information system**. The file system is the database, the text editor is the UI, and git is the sync layer. The `.mps` DSL is lightweight, human-writable, and machine-parseable without a grammar library.
+
+Philosophy: **structured data that looks like prose**. Every design decision flows from keeping files readable in any text editor while remaining richly queryable at the command line.
+
+---
+
+## 2. Load Order
+
+```
+lib/mps.rb
+  require mps/version
+  require mps/mps          ← MPS module methods
+  require mps/constants
+  require mps/config
+  require mps/interpolators/interpolators
+  require mps/elements/elements
+  require mps/engines/engines
+  require mps/ref_resolver      ← Phase 3
+  require mps/query             ← Phase 7
+  require mps/presenter         ← Phase 7
+  require mps/store
+  require cli/mps               ← thin dispatcher (defines MPS::CLI::MPS)
+  require mps/cli/commands      ← auto-discovers lib/mps/cli/commands/*.rb
+```
+
+Each layer depends only on layers above it. No circular dependencies.
+
+---
+
+## 3. Macro Architecture
+
+```
+exe/mps
+  └─ MPS::CLI::MPS (Thor, thin dispatcher)
+       │   shared helpers: init, store, date_range, type_badge,
+       │                   print_tree, format_duration, auto_git_cmd
+       │
+       ├─ lib/mps/cli/commands/*.rb  (self-registering via class_eval)
+       │    open, list, append, update, done, search, stats,
+       │    export, git, autogit, cmd, config, tags, version
+       │
+       ├─ MPS::Query          ← filter predicate object (Phase 7)
+       ├─ MPS::Presenter      ← rendering object (Phase 7)
+       ├─ MPS::RefResolver    ← human↔epoch ref translation (Phase 3)
+       │
+       └─ MPS::Store          ← all filesystem operations
+            └─ MPS::Engines::Parser  ← stack machine parser
+                 └─ MPS::Elements.*  ← typed value objects
+```
+
+---
+
+## 4. Micro Architecture
+
+### 4.1 The `.mps` DSL (unchanged from v0.5)
+
+```
+@type[arg1, key: val]{
+  body
+  @nested_type{ child }
+}
+```
+
+Optional brackets; arbitrary nesting; comma-separated args where bare words → tags and `key: val` → named attrs.
+
+### 4.2 Element Schema DSL (Phase 2)
+
+The core architectural addition of v1. Each element class declares a typed attribute schema using a class macro:
+
+```ruby
+class Task
+  include Element
+  SIGNATURE_STAMP = "task"
+  SIGNATURE_REGEX = /\Atask\z/
+
+  attribute :status, type: :string, default: "open", flag: "status", aliases: ["-s"]
+end
+```
+
+`Element.included` extends the class with `ClassMethods`, which provides:
+- `attribute(name, type:, default:, flag:, aliases:)` — declares a schema entry
+- `schema` — frozen public view of declared attributes
+- `_schema` — mutable backing store (used internally and in tests)
+- `parse_args(raw)` — schema-driven implementation; subclasses no longer override this
+
+**Guiding principle**: adding a new attribute to an element requires exactly one schema declaration. The parser, filter predicates, export output, and future CLI option generation all derive from that single declaration.
+
+Current schema per type:
+
+| Type | Attributes |
+|------|------------|
+| Task | `:status` (default: "open") |
+| Log | `:start`, `:end` |
+| Reminder | `:at` |
+| Note | — (tags only) |
+| MPS | — (tags only) |
+
+### 4.3 Parser (unchanged algorithm, extended interface)
+
+Single-pass stack machine. Position-advancing via `Regexp#match(str, pos)`. Returns a flat `{ "YYYYMMDD.n.m" => element }` hash. Ref-path encoding: date integer (YYYYMMDD) as the epoch base, then sequential child counters.
+
+**v1 extension**: accepts `interpolator_classes:` keyword argument. After the main parse loop, `_apply_interpolations` mutates body strings in-place for any registered interpolator patterns.
+
+Backward-compat alias: `Engines::MPS = Engines::Parser` retained.
+
+### 4.4 RefResolver (Phase 3)
+
+`MPS::RefResolver.new(elements_hash)` builds a bidirectional mapping between epoch refs and human refs at construction time.
+
+**Human ref format**:
+- Top-level: `{type}-{n}` where `n` is sequential per type (e.g. `task-1`, `note-2`)
+- Nested: `{parent_human}.{child_index}` (e.g. `mps-1.1`, `task-2.3`)
+
+**API**:
+- `to_human(epoch_ref)` → human ref string or nil
+- `to_epoch(human_ref)` → epoch ref string or nil
+- `resolve(ref_str)` → epoch ref (accepts either form)
+- `all_epoch_refs` → sorted list
+
+The resolver is ephemeral — instantiated per-request, not cached. Store exposes `resolver_for(date)`.
+
+### 4.5 Store (extended for Phase 3 + Phase 4)
+
+`MPS::Store.new(storage_dir)` now also collects `@interpolator_classes` and passes them to every parser call.
+
+**New methods**:
+- `resolver_for(date)` → `RefResolver` for that date's elements
+- `rewrite_element(ref_str, new_attrs, date: Date.today)` → boolean
+
+`rewrite_element` accepts both epoch refs and human refs. Human refs are resolved using a `RefResolver` for the given date. The rewrite:
+1. Reads the file into memory
+2. Parses to find the element and its `raw_args`
+3. Merges `new_attrs` over existing `parsed_args`, preserving tags
+4. Builds a new args string (`attr: val` pairs first, then tags)
+5. Replaces the `@type[old_args]{` opening via `String#sub` with a compiled regex
+6. Writes to `path.tmp.PID` then `File.rename` (atomic on POSIX)
+
+**Known limitation**: if the same type+args combination appears multiple times in a file, `sub` replaces only the first occurrence. For typical personal files this is acceptable.
+
+### 4.6 Query (Phase 7)
+
+`MPS::Query.new(opts)` encapsulates all filter logic. No Thor dependency.
+
+- `apply(elements_hash)` → filtered hash (MPS containers excluded)
+- `apply_for_tree(elements_hash)` → filtered hash preserving MPS containers when their children are visible
+
+Schema-driven attr filters: iterates all element classes' schemas, maps `flag:` → `opts[flag_sym]`, applies as filter predicates. Adding `attribute :location, flag: "location"` to Task automatically makes `Query.new(location: "home")` filter by location.
+
+### 4.7 Presenter (Phase 7)
+
+`MPS::Presenter.new(elements_hash, color_fn:, resolver:, with_refs:)` renders to string without Thor dependency.
+
+- `render_tree` → [rendered_string, shown_count]
+- `render_element(el, depth:)` → single line string
+- `render_tag_table` → tag frequency table string
+
+Colorization is injected via `color_fn:` proc. CLI passes `method(:set_color)` from Thor context. Tests use the default ANSI fallback or plain text (color_fn: nil disables ANSI).
+
+### 4.8 CLI Modularization (Phase 5)
+
+`lib/cli/mps.rb` is now a **thin dispatcher**. It defines:
+- Thor class header (class_option, default_task, exit_on_failure)
+- `self.start` override for `default_command` config
+- `version` command (tiny, lives here)
+- All private shared helpers
+
+**Each command is a separate file** under `lib/mps/cli/commands/`. Commands self-register by calling `MPS::CLI::MPS.class_eval { ... }` at load time. This works because `cli/mps.rb` (the dispatcher) is loaded before `mps/cli/commands` in `lib/mps.rb`.
+
+`lib/mps/cli/commands.rb` auto-discovers and loads all `*.rb` files in the `commands/` directory:
+
+```ruby
+Dir[File.join(__dir__, "commands", "*.rb")].sort.each { |f| require f }
+```
+
+**Adding a command = adding a file. No other changes required.**
+
+---
+
+## 5. Design Patterns
+
+| Pattern | Where |
+|---------|-------|
+| Schema DSL (class macro) | `Element.attribute` |
+| Registry via module constants | Elements, Interpolators auto-discovery |
+| Mixin composition | `Element` mixin included by all element types |
+| Command self-registration | `class_eval` on dispatcher |
+| Auto-discovery loader | `mps/cli/commands.rb` globs directory |
+| Dependency injection | `color_fn:` in Presenter |
+| Atomic file write | tmp + rename in `rewrite_element` |
+| Resolver pattern | `RefResolver` translates between ref forms |
+| Query object | `MPS::Query` encapsulates filter predicates |
+
+---
+
+## 6. Dependency Layering
+
+```
+Constants → Config → Elements (schema DSL)
+                   → Engines::Parser (uses element classes + interpolators)
+                   → RefResolver (uses elements hash)
+                   → Query (uses element schemas)
+                   → Presenter (uses element classes + Query)
+                   → Store (uses Parser + RefResolver)
+                   → CLI dispatcher (uses Store + Query + Presenter)
+                        → command files (CLI layer)
+```
+
+**The CLI never instantiates Elements directly.** Store is the only gateway.
+
+---
+
+## 7. Resolved Technical Debt (v0.5 → v1.0)
+
+| Debt item | Resolution |
+|-----------|-----------|
+| `git` / `autogit` code duplication | Extracted `auto_git_cmd` private method |
+| Dead `display_str` / `disp_str` / `PADDING` | Removed from Element mixin |
+| `get_filename_from_date` epoch mismatch | Delegates to `MPS_NEW_FILE_NAME_GEN` |
+| `Engines::MPS` in tests | Updated to `Engines::Parser` |
+| `Config#mps_dir` missing | Added `attr_reader :mps_dir` |
+| `stats` inline duration math | Uses `format_duration` helper |
+| Bespoke `parse_args` per element | Replaced by schema-driven `ClassMethods#parse_args` |
+| `visible?` hardcoded `:status` | Schema-driven attr filters in `Query` |
+| CLI monolith | Modularized into `commands/` directory |
+| Interpolators unconnected | Wired via `interpolator_classes:` param |
+| No mutation path | `Store#rewrite_element` + `update`/`done` commands |
+| No human-readable refs | `RefResolver` + `--refs` flag on `list` |
+
+---
+
+## 8. Remaining Known Issues
+
+| Issue | Notes |
+|-------|-------|
+| `rewrite_element` replaces first occurrence only | Acceptable for personal files; needs position tracking for robustness |
+| `Engines::MPS = Parser` alias | Retained for backward compat; can be removed in v1.1 |
+| Human refs for today only | Epoch refs work for any date; human refs require `--date` for non-today |
+
+---
+
+## 9. Extension Points
+
+### Adding a new element type
+
+1. Create `lib/mps/elements/widget.rb` with `class MPS::Elements::Widget; include Element; SIGNATURE_STAMP = "widget"; SIGNATURE_REGEX = /\Awidget\z/`
+2. Declare attributes: `attribute :foo, type: :string, flag: "foo"`
+3. Add `require_relative "./widget"` to `elements/elements.rb`
+
+Parser, Store, Query, and Presenter all pick it up automatically. The CLI `append` command accepts the type. `update` options are generated from the schema at class-load time.
+
+### Adding a new command
+
+1. Create `lib/mps/cli/commands/mycommand.rb`
+2. Write `MPS::CLI::MPS.class_eval { desc "mycommand ARGS", "desc"; def mycommand(...) ... end }`
+3. No other changes required — the auto-discovery loader picks it up
+
+### Adding a new interpolator
+
+1. Create `lib/mps/interpolators/myinterp.rb` with `SIGNATURE_REGEX = /:myinterp/` and `get_str`
+2. Add `require_relative "./myinterp"` to `interpolators/interpolators.rb`
+
+The store passes all discovered interpolators to the parser automatically.
+
+---
+
+## 10. Phase Roadmap Summary
+
+| Phase | Scope | Status |
+|-------|-------|--------|
+| 1 | Technical debt cleanup | ✓ Done |
+| 2 | Element attribute schema DSL | ✓ Done |
+| 3 | RefResolver (human-readable refs) | ✓ Done |
+| 4 | Element mutation (`rewrite_element`, `update`, `done`) | ✓ Done |
+| 5 | CLI modularization (self-registering commands) | ✓ Done |
+| 6 | Surface expansion (`tags`, `config`, `default_command`, `aliases`, interpolators) | ✓ Done |
+| 7 | Query + Presenter extraction | ✓ Done |
+
+**Out of scope for v1**: interactive TUI, LLM integration, cross-file `@ref` linking, SQLite search index.
+
+---
+
+## 11. Next Architectural Moves (v1.1+)
+
+- **Position tracking in parser**: store byte offsets per element for robust rewrite (no collision risk)
+- **SQLite search index**: for sub-second search over large archives
+- **Cross-file `@ref` element**: using epoch refs as stable identifiers
+- **Query language**: `mps query "type:task AND tag:work since:monday"`
+- **Rust parser rewrite**: for performance-critical path (parser + store)
+- **Remove `Engines::MPS` alias** now that all callers use `Engines::Parser`

data/CLAUDE.md

@@ -39,30 +39,26 @@ bundle exec exe/mps append TYPE BODY [--tags work,release] [--at 3pm]
 bundle exec exe/mps autogit
 ```
 
-Set `MPS_DEBUG=true` to enable verbose `require_relative` tracing via the custom `ir()` loader.
-
 ## Architecture
 
 ### Entry point
 `exe/mps` calls `MPS::CLI::MPS.start(ARGV)` — a Thor-based CLI defined in `lib/cli/mps.rb`. All commands (`open`, `git`, `autogit`, `list`, `append`, `cmd`, `version`) live there and delegate to the library layer.
 
-### Custom loader (`ir`)
-`lib/mps/mps.rb` defines a global helper `ir(relative_path)` that wraps `require_relative` with caller-location resolution. All internal requires use `ir` instead of `require_relative`. This is intentional — don't replace it with standard requires.
-
 ### Load order (`lib/mps.rb`)
 ```
-mps/version → mps/mps (defines ir + MPS module methods) →
-  mps/constants → mps/config → mps/interpolators → mps/elements → mps/engines → cli/mps
+mps/version → mps/mps (MPS module methods) →
+  mps/constants → mps/config → mps/interpolators → mps/elements → mps/engines →
+  mps/ref_resolver → mps/query → mps/presenter → mps/store → cli/mps → mps/cli/commands
 ```
 
 ### Parsing pipeline (`lib/mps/engines/mps.rb`)
-`Engines::MPS.parse_mps_file_to_elments_hash` reads an `.mps` file and uses `StringScanner` to tokenize it. It wraps the raw file contents in a synthetic `@mps[]{}` root element, then does a single-pass scan driven by two regexes from `Constants`: `AT_REGEXP_LA` (lookahead for `@element[args]{`) and `END_CURLY_REGEXP_LA` (lookahead for `}`). A stack tracks nesting; each closed element is instantiated and stored in a flat hash keyed by a dotted ref path (e.g. `"1234567890.1.2"`).
+`Engines::Parser.parse_mps_file_to_elements_hash` reads an `.mps` file and uses a position-based stack parser with `Regexp#match(str, pos)`. It wraps the raw file contents in a synthetic `@mps[]{}` root element, then iterates using two regexes from `Constants`: `AT_REGEXP` (opening `@element[args]{`) and `END_CURLY_REGEXP` (closing `}`). A stack tracks nesting; each closed element is instantiated and stored in a flat hash keyed by a dotted ref path (e.g. `"1234567890.1.2"`). `Engines::MPS` is a backward-compat alias for `Engines::Parser`.
 
 ### Elements (`lib/mps/elements/`)
 Each element type (Task, Note, Reminder, Log, MPS) is a class that `include`s the `MPS::Element` mixin. The mixin provides `initialize(args:, refs:, body_str:)`, `display_str`, and `attr_reader :body_str`. Each class must define `SIGNATURE_STAMP` (used when generating filenames/wrapping) and `SIGNATURE_REGEX` (matched against the parsed element sign to dispatch). The engine discovers all element classes dynamically via `MPS::Elements.constants`.
 
 ### Interpolators (`lib/mps/interpolators/`)
-Interpolator classes (e.g. `Interpolators::Time`) are discovered the same way as elements — via `const_get` on the module's `constants`. Each defines `SIGNATURE_REGEX` and `get_str(**ref)`. They are loaded into `Engines::MPS` but the interpolation call-site is not yet wired up in the engine.
+Interpolator classes (e.g. `Interpolators::Time`) are discovered the same way as elements — via `const_get` on the module's `constants`. Each defines `SIGNATURE_REGEX` and `get_str`. The parser applies them to body strings after the main parse loop via `_apply_interpolations`.
 
 ### Configuration (`lib/mps/config.rb` + `lib/mps/constants.rb`)
 `Config.init(path)` writes a default YAML config. `Config.new(**hash)` holds `storage_dir`, `mps_dir`, `log_file`, and a `Logger`. Two additional optional YAML keys are supported: `git_remote` (default `"origin"`) and `git_branch` (default `"master"`); both are exposed as `attr_reader`s and used by `git` and `autogit` commands. The CLI re-reads the config on every invocation via `load_config`; it auto-creates missing directories and the log file.
@@ -97,6 +93,6 @@ File names follow `YYYYMMDD.<epoch>.mps`; the epoch disambiguates multiple files
 
 Tests use Minitest with `fakefs` for filesystem isolation. The test helper at `test/test_helper.rb` sets up the load path and does `include MPS`, so all constants and module methods are available directly in test classes.
 
-`test/engine_test.rb` tests the parser directly: it uses a `parse_content(str)` helper that writes a fixture file under `FakeFS` at `/tmp/20260101.mps` and calls `Engines::MPS.parse_mps_file_to_elments_hash` on it. Covers empty files, single and multiple elements, unknown element fallback to `Struct`, nested `@mps{}`, `matched_element_class`, and `look_ahead_pos` edge cases.
+`test/engine_test.rb` tests the parser directly: it uses a `parse_content(str)` helper that writes a fixture file under `FakeFS` at `/tmp/20260101.mps` and calls `Engines::Parser.parse_mps_file_to_elements_hash` on it. Covers empty files, single and multiple elements, unknown element fallback to `Struct`, nested `@mps{}`, `matched_element_class`, and `look_ahead_pos` edge cases.
 
 `test/config_test.rb` covers `Config.init`, `Config.load_conf_hash` (including `git_remote`/`git_branch` defaults), logger formatting, and `LoadError` on missing keys.

data/GETTING_STARTED.md

@@ -93,6 +93,24 @@ mps list
 
 The nested tree is preserved — child elements appear indented under their parent `[@mps]` group. Each type gets its own color in the terminal.
 
+### Show human-readable refs
+
+Pass `--refs` (or `-r`) to see addressable references alongside each element:
+
+```bash
+mps list --refs
+```
+
+```
+  task-1        [task] (open) Review the API pull request [work]
+  reminder-1    [reminder] (10am) Team standup
+  note-1        [note] The auth token expiry edge case
+  mps-1         [@mps]
+  mps-1.1         [task] (open) Nested backend task [backend]
+```
+
+These refs (`task-1`, `note-1`, `mps-1.1`, …) can be passed to `update` and `done`.
+
 ### Filter by type
 
 Only want tasks?
@@ -121,8 +139,6 @@ mps list --status open
 mps list -s done
 ```
 
-Status filtering only applies to tasks — notes, logs, and reminders are excluded when you use `--status`.
-
 ### Look at a different day
 
 ```bash
@@ -197,10 +213,59 @@ The 3h30m duration is computed automatically and shown in `list`, `stats`, and `
 mps append reminder "Push the hotfix before EOD" --at "5pm"
 ```
 
+### Type aliases
+
+If you configure aliases in `~/.mps_config.yaml`:
+
+```yaml
+aliases:
+  t: task
+  n: note
+  r: reminder
+  l: log
+```
+
+You can use the short form:
+
+```bash
+mps append t "Quick task via alias"
+```
+
 All types supported by `append`: `task`, `note`, `log`, `reminder`.
 
 ---
 
+## Updating elements in-place
+
+Found a task you finished? Mark it done without opening Vim:
+
+```bash
+mps done task-1
+```
+
+Need to update an arbitrary attribute?
+
+```bash
+mps update task-1 --status done
+mps update reminder-1 --at "6pm"
+mps update log-1 --end-time 13:00
+```
+
+Refs can be the human-readable form (`task-1`, `note-2`, `mps-1.1`) shown by `mps list --refs`, or the epoch-based form (`20260428.1`) which encodes the date and position.
+
+```bash
+# Epoch ref — works for any date without needing --date
+mps done 20260421.2
+
+# Human ref — defaults to today
+mps done task-1
+
+# Human ref for another date
+mps done task-1 --date yesterday
+```
+
+---
+
 ## Search across all your files
 
 End of quarter. You vaguely remember logging something about "auth" in March. You don't know which file.
@@ -244,6 +309,28 @@ All filters compose: `mps search "auth" --type task --tag backend --since "last
 
 ---
 
+## Tag usage summary
+
+See which tags you're using most:
+
+```bash
+mps tags
+```
+
+```
+  work (7)
+  backend (4)
+  personal (2)
+```
+
+Filter by type or date range:
+
+```bash
+mps tags --type task --since monday
+```
+
+---
+
 ## Your productivity at a glance
 
 Friday afternoon. How did your week go?
@@ -300,12 +387,6 @@ CSV format:
 mps export --format csv
 ```
 
-```
-date,ref,type,tags,body,status,at,start,end
-2026-04-28,1745000000.1,task,work,Review the API pull request,open,,,
-2026-04-28,1745000000.2,reminder,,Team standup,,10am,,
-```
-
 All the same filters apply:
 
 ```bash
@@ -357,6 +438,60 @@ git_branch: main
 
 ---
 
+## Configuration management
+
+View your current configuration:
+
+```bash
+mps config show
+```
+
+```
+MPS configuration
+  config file : /home/you/.mps_config.yaml
+  mps_dir     : /home/you/.mps
+  storage_dir : /home/you/.mps/mps
+  log_file    : /home/you/.mps/mps.log
+  git_remote  : origin
+  git_branch  : main
+  default_cmd : open
+```
+
+Open your config file in `$EDITOR`:
+
+```bash
+mps config edit
+```
+
+### Configuring the default command
+
+By default, bare `mps` opens today's file in Vim. To make `mps` list instead:
+
+```yaml
+default_command: list
+```
+
+### Type aliases
+
+Create short names for element types in your config:
+
+```yaml
+aliases:
+  t: task
+  n: note
+  r: reminder
+  l: log
+```
+
+Then use them with `append`:
+
+```bash
+mps append t "Quick capture"       # same as: mps append task
+mps append n "Remember this"       # same as: mps append note
+```
+
+---
+
 ## Run any shell command in your storage directory
 
 Need to see what files exist, or grep across everything raw?
@@ -388,9 +523,13 @@ mps version
 | `mps` / `mps open [date]` | Open a date's file in Vim (default: today) |
 | `mps list [date]` | Print elements in tree order (default: today) |
 | `mps append TYPE BODY` | Add one element to today's file without Vim |
+| `mps update REFPATH [--attr val]` | Update an element's attributes in-place |
+| `mps done REFPATH` | Mark a task as done (shorthand for update --status done) |
 | `mps search QUERY` | Full-text search across all files |
+| `mps tags [date]` | Show tag usage counts |
 | `mps stats [date]` | Element counts and log durations for a date |
 | `mps export [date]` | Export elements as JSON or CSV to stdout |
+| `mps config [show\|edit]` | View or edit configuration |
 | `mps autogit` | Stage, commit, pull, push in one shot |
 | `mps git ARGS` | Run any git command inside storage dir |
 | `mps cmd ARGS` | Run any shell command inside storage dir |
@@ -404,6 +543,7 @@ mps version
 | `--tag TAG` | `-g` | Filter by tag name |
 | `--status STATUS` | `-s` | Filter tasks by: `open`, `done` |
 | `--since DATESIGN` | `-S` | Show elements from SINCE up to DATESIGN |
+| `--refs` | `-r` | Show human-readable ref column |
 
 ### append options
 
@@ -415,6 +555,18 @@ mps version
 | `--start-time HH:MM` | Start time for logs |
 | `--end-time HH:MM` | End time for logs |
 
+### update options
+
+All schema-declared attributes are available as flags. Current built-in:
+
+| Option | Description |
+|--------|-------------|
+| `--status STATUS` | New status value |
+| `--at TIME` | New time for reminders |
+| `--start-time HH:MM` | New start time for logs |
+| `--end-time HH:MM` | New end time for logs |
+| `--date DATESIGN` | Date context for human refs (default: today) |
+
 ### search options
 
 | Option | Short | Description |
@@ -437,6 +589,14 @@ mps version
 | `--type TYPE` | `-t` | Filter by element type |
 | `--since DATESIGN` | `-S` | Export from SINCE up to DATESIGN |
 
+### tags options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--type TYPE` | `-t` | Filter by element type |
+| `--since DATESIGN` | `-S` | Show tags from SINCE up to DATESIGN |
+| `--status STATUS` | `-s` | Filter tasks by status before counting |
+
 ### Date formats accepted everywhere
 
 | Input | Meaning |
@@ -445,3 +605,11 @@ mps version
 | `monday`, `last friday` | Day of week |
 | `2 days ago`, `last week` | Natural language |
 | `20260421` | Explicit YYYYMMDD |
+
+### Ref formats accepted by update and done
+
+| Format | Example | Scope |
+|--------|---------|-------|
+| Human top-level | `task-1` | Today's file (or `--date`) |
+| Human nested | `mps-1.1` | Today's file (or `--date`) |
+| Epoch-based | `20260428.2` | Any date (encoded in prefix) |