Refresh README, enable runtime writes, add plans

Update README CLI guidance to reflect the manifest-driven workflow: reorganize examples into Inspect/Execute/Trajectory sections, clarify `nqctl act` vs `actions list` vs `capabilities`, and remove legacy parameter-authoring commands. Change runtime defaults in config/default_runtime.yaml to allow_writes: true and dry_run: false. Add planning/design and implementation documents under docs/plans that describe an anchor-based cutoff for Nanonis action discovery (Bias_Set) and the README refresh implementation steps, including testing and verification guidance.

Author: BB-84C

README.md

@@ -65,105 +65,111 @@ python -m pip install ".[nanonis]"
 
 Runtime config controls host, candidate ports, timeout, backend, write policy, and trajectory settings.
 
-## CLI quickstart (`nqctl`)
+## CLI command guide (`nqctl`)
 
-Show capability contract:
+### Inspect and introspect
 
-```powershell
-nqctl capabilities
-```
-
-Read one parameter:
+Get the machine-readable CLI contract (parameters, action commands, policy):
 
 ```powershell
-nqctl get bias_v
+nqctl capabilities
 ```
 
-Guarded single-step set:
+Include backend command discovery from the active backend:
 
 ```powershell
-nqctl set bias_v 0.12
+nqctl capabilities --include-backend-commands --backend-match Scan
 ```
 
-Explicit guarded ramp:
+List observable parameter metadata and high-level CLI action descriptors:
 
 ```powershell
-nqctl ramp bias_v 0.10 0.25 0.01 --interval-s 0.10
+nqctl observables list
+nqctl actions list
 ```
 
-Invoke one manifest action command:
-
-```powershell
-nqctl act Scan_Action --arg Scan_action=0 --arg Scan_direction=1
-```
-
-Inspect effective policy:
+Inspect active policy, backend command inventory, and connectivity preflight:
 
 ```powershell
 nqctl policy show
+nqctl backend commands --match Bias
+nqctl doctor --command-probe
 ```
 
-## Trajectory monitor quickstart (`nqctl`)
+### Execute operations
 
-Inspect monitor defaults and available labels:
+Read one parameter:
 
 ```powershell
-nqctl trajectory monitor config show
-nqctl trajectory monitor list-signals
-nqctl trajectory monitor list-specs
+nqctl get bias_v
 ```
 
-Stage a run configuration (required before each run):
+Apply guarded strict single-step write:
 
 ```powershell
-nqctl trajectory monitor config set --run-name gui-play-001 --interval-s 0.1 --rotate-entries 6000 --action-window-s 2.5
+nqctl set bias_v 0.12
 ```
 
-Start monitoring (foreground; stop with `Ctrl+C`):
+Apply explicit guarded ramp:
 
 ```powershell
-nqctl trajectory monitor run
+nqctl ramp bias_v 0.10 0.25 0.01 --interval-s 0.10
 ```
 
-Inspect action trajectory from SQLite:
+Invoke one manifest action command with argument overrides:
 
 ```powershell
-nqctl trajectory action list --db-path artifacts/trajectory/trajectory-monitor.sqlite3 --run-name gui-play-001
-nqctl trajectory action show --db-path artifacts/trajectory/trajectory-monitor.sqlite3 --run-name gui-play-001 --action-idx 0 --with-signal-window
+nqctl act Scan_Action --arg Scan_action=0 --arg Scan_direction=1
 ```
 
-Notes:
-- `run_name` is cleared after each monitor run, so set it again before the next run.
-- Action entries use ISO UTC timestamps and include `delta_value` for numeric spec changes.
-- Legacy JSONL readers remain available via `nqctl trajectory tail` and `nqctl trajectory follow`.
+### `act` vs action metadata
 
-JSON is the default output format. Use `--text` for human-readable key/value output.
+- `nqctl act <action_name> --arg key=value` executes one backend action command from
+  the manifest `actions` section.
+- `nqctl actions list` lists CLI-level action descriptors (what workflows the CLI
+  supports, with safety hints and templates).
+- `nqctl capabilities` exposes executable manifest action inventory under
+  `action_commands.items[*]` (command name, args, arg types, safety mode).
 
-Help shortcuts:
+### Trajectory commands
+
+Legacy JSONL readers:
 
 ```powershell
-nqctl -help
-nqctl -help parameters
+nqctl trajectory tail --directory artifacts/trajectory --limit 20
+nqctl trajectory follow --directory artifacts/trajectory --interval-s 0.5
 ```
 
-## Parameter extension workflow
-
-Discover candidate backend commands:
+SQLite action queries:
 
 ```powershell
-nqctl parameters discover --match LockIn
+nqctl trajectory action list --db-path artifacts/trajectory/trajectory-monitor.sqlite3 --run-name gui-play-001
+nqctl trajectory action show --db-path artifacts/trajectory/trajectory-monitor.sqlite3 --run-name gui-play-001 --action-idx 0 --with-signal-window
 ```
 
-Regenerate the unified parameter manifest:
+Monitor config and run loop:
 
 ```powershell
-python scripts/generate_parameters_manifest.py --output config/parameters.yaml
+nqctl trajectory monitor config show
+nqctl trajectory monitor config set --run-name gui-play-001 --interval-s 0.1 --rotate-entries 6000 --action-window-s 2.5
+nqctl trajectory monitor list-signals
+nqctl trajectory monitor list-specs
+nqctl trajectory monitor run
+nqctl trajectory monitor config clear
 ```
 
-Validate parameter YAML:
+Notes:
+- `run_name` is cleared after each monitor run attempt; set it again before the next run.
+- Action entries use ISO UTC timestamps and include `delta_value` for numeric spec changes.
+
+### Output and help
+
+JSON is the default output format. Use `--text` for human-readable key/value output.
 
 ```powershell
-nqctl parameters validate --file config/parameters.yaml
+nqctl -help
+nqctl -help trajectory
+nqctl -help act
 ```
 
 ## QCodes usage

config/default_runtime.yaml

@@ -11,8 +11,8 @@ nanonis:
   backend: "adapter"
 
 safety:
-  allow_writes: false
-  dry_run: true
+  allow_writes: true
+  dry_run: false
   default_ramp_interval_s: 0.05
 
 trajectory:

docs/plans/2026-02-24-action-surface-cutoff-design.md

@@ -0,0 +1,73 @@
+# Action Surface Cutoff Design
+
+Date: 2026-02-24
+
+## Goal
+
+Constrain manifest import to the intended Nanonis command surface by ignoring
+class-callable members declared before `Bias_Set` in `nanonis_spm.Nanonis`.
+This removes internal helper methods from generated `actions` while preserving
+the current Get/Set parameter extraction and action generation flow.
+
+## Decision
+
+Use positional anchoring (Option 1):
+
+- Discover candidate methods in class declaration order.
+- Find `Bias_Set` as the anchor.
+- Exclude all callable members before the anchor.
+- Keep existing manifest behavior after discovery (split Get/Set to
+  `parameters`, non-Get/Set to `actions`).
+
+Rationale:
+
+- Matches the requested contract exactly.
+- Simple, deterministic, and low maintenance for a mostly stable upstream
+  class layout.
+
+## Design
+
+### Discovery pipeline
+
+Update `discover_nanonis_commands` in
+`nanonis_qcodes_controller/qcodes_driver/manifest_generator.py`:
+
+1. Read ordered members from `nanonis_spm.Nanonis.__dict__.items()`.
+2. Keep callable members that do not start with `_`.
+3. Locate the first member named `Bias_Set`.
+4. Slice the ordered member list from `Bias_Set` onward.
+5. Apply optional `match_pattern` filtering.
+6. Build `CommandInfo` entries from remaining members.
+7. Sort resulting commands by command name before returning (to keep stable
+   generated YAML ordering independent of declaration order).
+
+### Error handling
+
+- If `Bias_Set` is not found in callable members, raise `ValueError` with a
+  clear message indicating that command discovery cannot establish the Nanonis
+  anchor.
+
+### Compatibility
+
+- No schema changes to `config/parameters.yaml`.
+- No CLI contract changes (`nqctl capabilities`, `nqctl act` stay the same).
+- Existing curated merge behavior remains unchanged.
+
+## Testing strategy
+
+Add/extend tests in `tests/test_parameter_manifest_generator.py`:
+
+- Verify methods before `Bias_Set` are excluded by discovery.
+- Verify methods at/after `Bias_Set` are included.
+- Verify missing-anchor behavior raises a clear `ValueError`.
+
+Run focused tests first, then full project checks before any release actions.
+
+## Risks and mitigations
+
+- Risk: upstream reorders class members unexpectedly.
+  - Mitigation: fail fast when anchor is missing; tests exercise cutoff logic.
+- Risk: inherited members might not appear in `__dict__`.
+  - Mitigation: this design intentionally tracks the concrete class declaration
+    surface; if upstream moves methods to a base class, update discovery rule
+    explicitly in a follow-up.