NODARAMA VERBATIM — CURRENT RECORDER MANIFEST REFERENCE

Source of truth: `recorder.ts`

Core Manifest Shape

{
  "Task": "required descriptive task label",
  "Action": "required supported action name",
  "FilePath": "required target path and filename",
  "Payload": "required action-specific payload",
  "Comment": "optional human-readable note"
}

Field Notes

* Recorder supports file write, rewrite, replace, and insert operations.
* Tasks should be very brief but specific: it should be kept to a minimum length that describes a reference in the code and objective

Current Recorder Action Set

* `newfile`
* `rewritefile`
* `replacestring`
* `replaceall`
* `replaceblock`
* `replacefunction`
* `insertbefore`
* `insertafter`

Action Details

`newfile`

* Creates a new file.
* Fails if the target file already exists.
* `Payload` must be the full file contents as a string.

`rewritefile`

* Rewrites the full contents of an existing file.
* Fails if the target file is missing.
* Creates rewrite protection backup before writing.
* `Payload` must be the full replacement file contents as a string.

`replacestring`

* Replaces the first exact string match in a file.
* `Payload` must be an object with:
  * `target`
  * `replacement`
* Fails if `target` is missing, not found, or if the edit makes no change.

`replaceall`

* Replaces every exact string match in a file.
* `Payload` must be an object with:
  * `target`
  * `replacement`
* Fails if `target` is missing, not found, or if the edit makes no change.
* Reports the number of occurrences replaced.

`replaceblock`

* Replaces content between two unique line boundaries.
* `Payload` must be an object with:
  * `start`
  * `end`
  * `replacement`
* `start` must match exactly one line after trimming whitespace.
* `end` must match exactly one line after trimming whitespace.
* `end` must appear after `start`.
* Recorder preserves the `start` line.
* Recorder inserts `replacement` after the preserved `start` line.
* Recorder preserves the `end` line and everything after it.
* In practice, this replaces the lines between `start` and `end`, not the boundary lines themselves.

`replacefunction`

* Replaces one complete top-level function or method-sized unit.
* `Payload` must be an object with:
  * `start`
  * `replacement`
* `start` must match exactly one line after trimming whitespace.
* The matched `start` line must be recognized as a top-level function start.
* Recorder replaces from the matched `start` line through the line before the next top-level function boundary.
* The next top-level function boundary is preserved.
* Use this only for complete top-level functions or top-level method-sized units.
* Do not use this for inner helper fragments.

`insertbefore`

* Inserts content before one unique exact string match.
* `Payload` must be an object with:
  * `find`
  * `content`
* Fails if `find` is missing, not found, or not unique.

`insertafter`

* Inserts content after one unique exact string match.
* `Payload` must be an object with:
  * `find`
  * `content`
* Fails if `find` is missing, not found, or not unique.

Payload Rules

String payload actions:

* `newfile`
* `rewritefile`

Object payload actions:

* `replacestring`
* `replaceall`
* `replaceblock`
* `replacefunction`
* `insertbefore`
* `insertafter`

Path and Scope Notes

* `FilePath` is resolved by Recorder against the current active project context.
* Backstage Universal mode can write against the app root.
* Non-backstage or restricted project modes may block paths outside permitted project roots.
* Absolute paths and relative paths are normalized and checked against allowed write roots.

Guidance

* Read the target file before authoring a manifest whenever possible.
* Prefer the smallest safe action.
* Use `replacestring` for precise small edits.
* Use `replaceall` only when every exact occurrence should change.
* Use `insertbefore` or `insertafter` when adding content near a unique anchor.
* Use `replaceblock` when replacing a section bounded by stable lines.
* Use `replacefunction` only when replacing a whole top-level function or method-sized unit.
* Use `newfile` only when creating a missing file.
* Use `rewritefile` only when a full-file rewrite is safer than many smaller edits.
* Treat Recorder as a write, replace, and insert system, not a general file-operation or shell-command system.

