# Customize this file for your environment.
# Replace <YOUR_SCRIPTS_DIR> with your actual scripts directory path.
# Replace <YOUR_HOME> with your user home directory (e.g. C:\Users\yourname).
#
# This file is meant to be copied to clipboard and pasted into AI chat sessions
# to teach the AI your clipboard-based patch workflow.

When we code together, use my clipboard-based patch commands to deliver edits. Here is how they work.

============================================
OVERVIEW
============================================
I have PowerShell commands that read structured clipboard content and apply it to files.
After I copy your code block, I type a short alias (file, drop, fold, ins, nix) to apply it.
In practice, everything is delivered as BATCH — I copy one block and execute with a hotkey.
Every write auto-backs up the target file and runs a syntax check.
Syntax check results are captured to clipboard so I can paste them back to you.

Please note that file addresses must be enclosed in quotes if they contain spaces.

============================================
FILE  (alias: file)
============================================
Purpose: Write an entire file (new or complete rewrite).
Clipboard format:
  Line 1:  # path/filename.ext
  Lines 2+: full file content

Rules:
  - Path can be absolute or relative to my current directory.
  - The # header line is kept for .ps1/.py files but stripped for web types (.ts, .tsx, .js, .jsx, .html, .css, .json, .xml, .yaml, .yml, .md).
  - If the file already exists, a timestamped backup is created automatically.
  - file -Append appends instead of overwriting.
  - file -Clean skips auto-injected run logging.
  USE WHEN: Creating a new file, or replacing an entire file.

============================================
DROP  (alias: drop)
============================================
Purpose: Replace a single function in an existing file.
Clipboard format:
  Line 1:  # filename.ext
  Line 2:  exact function signature (e.g., 'function Get-Data {' or 'def process_row(df):')
  Lines 3+: complete replacement function body

Rules:
  - The signature on line 2 must EXACTLY match (after Trim()) the existing signature in the file.
  - If the signature doesn't match, drop prompts interactively: Replace / Append / Skip.
  - If the function isn't found at all, it's appended as a new function.
  - Indentation is auto-shifted to match the file's existing indentation.
  - File is resolved by checking: current directory, then ~/Scripts, then profile directory.
  USE WHEN: Replacing one function entirely.
  DO NOT USE FOR: Decorated methods, partial edits — use fold instead.

============================================
FOLD  (alias: fold)
============================================
Purpose: Replace a section of a file using explicit old/new blocks.

Clipboard format:
  # filename.ext [?]
  <<<
  old line 1 (must exist in file)
  old line 2
  old line 3
  >>>
  new line 1
  new line 2

Rules:
  - Lines between <<< and >>> are the OLD block. They are matched consecutively
    in the file (each line compared after Trim()).
  - Lines after >>> are the NEW block. They replace the matched old block.
  - The old block must match ALL lines consecutively somewhere in the file.
  - The new block can be any length — shorter, longer, or same as old.
  - An empty new block deletes the matched section.
  - Indentation is auto-shifted to match the file indentation at the match point.
  - ? in the header enables preview mode (shows diff, no modification).
  - Aim for 3-5 old lines — enough to match uniquely, not the whole function.
  - Pick lines with distinctive content (avoid common patterns like blank lines or closing braces).

============================================
INS  (alias: ins)
============================================
Purpose: Insert clipboard content at a specific line number or at end of file.
Clipboard format:
  Line 1:  # filename.ext 42
  Lines 2+: content to insert

  Inserts BEFORE line 42. Existing content shifts down.

  Line 1 variant:  # filename.ext end
  Appends content at the end of the file.

============================================
NIX  (alias: nix)
============================================
Purpose: Remove lines from a file. No clipboard needed.
  nix file.ts 10 25       — remove lines 10 through 25
  nix file.ts 10          — remove line 10
  nix file.ts -StartAnchor "# START" -EndAnchor "# END"   — remove by anchor strings

============================================
BATCH  (alias: batch)
============================================
Purpose: Apply multiple edit operations in one clipboard paste.
This is the PRIMARY delivery method — format all edits as batch.

Clipboard format:
  #-# file
  # path/newfile.ext
  <full file content>
  #-# fold
  # existingfile.ext
  <<<
  old lines
  >>>
  new lines
  #-# drop
  # existingfile.ext
  <function signature and body>
  #-# ins
  # existingfile.ext 42
  <lines to insert>

  #-# run
  ! pip install requests
  ! python -m pytest tests/

Rules:
  - Each section begins with #-# followed by the command (file, fold, drop, ins, nix, run).
  - Edits to the SAME file are grouped: one backup, one write.
  - #-# run executes commands directly in PowerShell. "!" prefix on lines is stripped automatically.
  - batch -Preview shows diffs without modifying files.
  - ORDER: code/script files FIRST, commands/run sections AFTER, documentation LAST.
  - After completion, a full summary (including syntax check results and run output) is copied to clipboard.
    I will paste this back to you if there are errors.

============================================
PROBE  (alias: probe)
============================================
Purpose: Execute clipboard content directly as code.
  probe              — auto-detect language and run
  probe python       — force Python
  probe pwsh         — force PowerShell

Rules:
  - Auto-detects language from file path headers or code content.
  - If content contains Python signals (import, def, print, etc.), runs as Python.
  - Otherwise defaults to PowerShell — so any clipboard content runs directly.
  - Strips #-# headers and # path headers before execution.
  - Output is captured to clipboard so I can paste results back to you.

============================================
INSPECTION COMMANDS
============================================
All inspection commands output to BOTH console and clipboard.

context file.ts "pattern":5       — show lines around match with radius 5
context file.ts 200:10            — show lines around line 200 with radius 10
context file.ts "patA":5 "patB":3 — multiple patterns with different radii
context file.ts,file2.ts "TODO":3 — search multiple files
  Default radius is 3 if omitted.

outline file.ts                   — show structural skeleton (functions, classes, exports)
outline file.ts utils.ts          — multiple files

peek FuncName [file]              — display a function; searches Scripts/ and profile if no file given

snap file.ts                      — copy whole file to clipboard, formatted for AI
snap file1.ts file2.ts            — multiple files
snap FuncName file.ts             — copy specific function from file
snap FuncName                     — search for function globally
  NOTE: function names go BEFORE the file they belong to.
  Example: snap helper1 helper2 utils.ts  — extracts both functions from utils.ts

diff file.ps1 [N]                 — compare file with its Nth most recent backup (default: 1)

rev file.ps1 [N|?]               — restore from backup
rev file.ps1 ?                   — list all backups for file
rev file.ps1 3                   — restore 3rd most recent backup
rev                              — restore most recent backup (any file)
rev "2026-04-09 14:30"           — restore all files in current dir to state at that time

============================================
TOKEN CHECK
============================================
Purpose: Ask the AI to self-estimate context window usage.
This is NOT an implemented command — it's a prompt for the AI to provide:
  - Estimated Context Window Usage (%)
  - Primary Memory Consumers
  - Recommendation (Proceed / Reset Soon)

============================================
CHOOSING THE RIGHT COMMAND
============================================
New file or full rewrite            → FILE
Replace one function                → DROP
Replace part of a file              → FOLD
Add code at line or end             → INS
Remove code                         → NIX
Multiple edits (PREFERRED)          → BATCH
Run shell commands in batch         → RUN (inside batch: #-# run)
Run code and capture output         → PROBE

============================================
FORMATTING RULES FOR AI
============================================
1. Always include the # header line first.
2. Prefer FULL file paths.
3. For fold: include enough unique old lines to match unambiguously.
4. For drop: signature must match exactly.
5. Deliver ALL edits as ONE copyable BATCH block.
6. Brief explanation → command → code block.
7. Combine edits to the same file when possible.
8. Be ready to correct syntax warnings — I'll paste them back.
9. Prefer FILE for structural HTML edits.
10. Use BATCH for multi-file edits (always).
11. Combine inspection commands whenever possible.
12. Prefer a single snap/outline/context request.
13. Keep README documentation updated alongside code changes when applicable.