Cheat sheets

Personal Organizer Agents

Five local organizer projects. What each builds, how to run it, its inputs, outputs, review files and checks.

  • Concepts and terms
  • Tasks and commands
  • Diagrams
  • Comparisons
  • Defaults and numbers
  • Troubleshooting
  • Questions and tips

Source

Node projects side by side#

FactorBookmark Path OrganizerCalendar Focus PlannerField Notes Map Builder
BuildsReading path pageFocus plan and ICS proposalsGeoJSON and a schematic map
Inputbookmarks tree, topicssample.ics, tasks.json, a dayobservations, radiusMeters
Outputsbookmarks.json, progress.json, report.htmlfocus.ics, plan.json, plan.htmlobservations.geojson, groups.json, report.html
Review filethird argument progress.jsonnonethird argument group-review.json
Never doesFetch linksChange an account calendarDownload photos or tiles

From bookmark-path-organizer/README.md, solution/cli.ts, calendar-focus-planner/README.md, solution/cli.ts, field-notes-map-builder/README.md, solution/cli.ts

Python projects side by side#

FactorDownload Folder Sort DeskCatalog Record Linker
BuildsFiling plan and duplicate groupsCrosswalk and merged catalog
Inputfolder, occupiedleft_csv, right_csv, threshold
Outputsmoves.json, duplicates.json, review.htmlcrosswalk.csv, merged-catalog.json, review.html
Review file--decisions decisions.json--decisions decisions.json
Never doesMove a fileMerge on similarity alone

From download-folder-sort-desk/README.md, solution/cli.py, catalog-record-linker/README.md, solution/cli.py

Run the reference#

CommandWhat it does
node cli.ts sample.json outputBookmark organizer or field notes map
node cli.ts <input.json> <dir> <review.json>Runs again with your downloaded review
node cli.ts sample.ics tasks.json 2026-10-14 output 10Calendar plan with a 10 minute buffer
python3 cli.py samples/input.json --output demo-outputDownload sort desk or catalog linker
python3 cli.py <input.json> --output <dir> --decisions decisions.jsonApplies your approvals
python3 scripts/project_test.py <project> --all --solution --strictGrades the reference

From bookmark-path-organizer/README.md, calendar-focus-planner/README.md, solution/cli.ts, download-folder-sort-desk/README.md, catalog-record-linker/README.md, field-notes-map-builder/README.md

Calendar planner steps#

1CLIsets the window from 09:00 to 17:00 UTC on thegiven day.2parseCalendarneeds UID, DTSTART and DTEND. It skips cancelledand transparent events.3availableSlotsadds the buffer around events, merges overlaps,then lists the gaps.4schedulesorts tasks by priority, then by id.5scheduleputs each task in the earliest gap that is longenough.6schedulelists a task that fits no gap as unscheduledwith a reason.7exportCalendarwrites proposals to focus.ics for manual import.

From solution/main.ts, solution/cli.ts, calendar-focus-planner/README.md

Download sort desk#

folderrecordscategoryplanapproved movesclientinput.jsonfolder, occupiedprocessinventory()path, size, sha256processcategorize()scores, evidenceprocessplan_moves()destination,duplicate_groupsprocessreview_plan()fingerprint, approvedstoremoves.jsonfor a file managerfolderrecordscategoryplanapproved movesclientinput.jsonfolder, occupiedprocessinventory()path, size, sha256processcategorize()scores, evidenceprocessplan_moves()destination,duplicate_groupsprocessreview_plan()fingerprint,approvedstoremoves.jsonfor a file manager

From solution/main.py, solution/cli.py, download-folder-sort-desk/API.md

Scoring rules#

Bookmark topic score
a keyword in a title adds 3. A keyword in notes adds 1.
Bookmark duplicates
same URL after the fragment is removed. Query strings stay significant.
File category
a known extension adds 3. The words workshop and handout add 1 to documents.
File collisions
a taken destination gets -2, -3 before the suffix, case-insensitive.
Catalog pair score
title Jaccard times 0.8 plus creator Jaccard times 0.2.
Nearby observations
distanceMeters() uses a spherical earth of radius 6371008.8 m.
Map groups
pairs within the radius join one connected component.

From solution/main.ts, download-folder-sort-desk/API.md, catalog-record-linker/API.md, solution/main.ts, field-notes-map-builder/README.md

Defaults and limits#

SettingDefaultNote
Calendar buffer minutes10Allowed range 0 to 120
Calendar output folderfocus-outputFourth CLI argument
Max tasks100Minutes 5 to 480, priority 1 to 5
threshold0.25Finite, from 0 to 1
Folder nesting32Deeper bookmark trees fail
Radius0..1000000Meters
approvedFalseEvery planned move starts unapproved
schema_version1In moves.json and merged-catalog.json

From solution/cli.ts, solution/main.ts, catalog-record-linker/API.md, solution/main.ts, solution/main.ts, solution/main.py

Error messages and fixes#

SymptomCauseFix
Expand recurrence and timezone values to UTC before importingRRULE or TZID in the ICSExpand events in the exporter first
Event needs UID, DTSTART and DTENDImplicit end or DURATIONWrite an explicit DTEND
stale approval: source content or destination plan changedFiles or plan changed after reviewUse the new decisions.json
output must be outside the input folderOutput inside the scanned folderPick another output path
Progress order must contain every current id exactly onceBookmarks changed after the downloadRun without the third argument
one-to-one match violatedOne record accepted twiceAccept each record in one pair only

From solution/main.ts, calendar-focus-planner/README.md, solution/main.py, solution/cli.py, solution/main.ts, solution/main.py, solution/main.ts

Write a review file#

TaskCode
Split a map group"decisions": {"<id>": "keep-separate"}
Keep a map group"decisions": {"<id>": "keep-group"}
Save reading order"order": [...], "completed": [...]
Approve file moves"approved": ["<path>"]
Accept a catalog pair"match": true, "values": {}
Version a Node review"schemaVersion": 1

From solution/main.ts, solution/main.ts, download-folder-sort-desk/README.md, catalog-record-linker/API.md

Worked examples#

Why is the sample busy from 09:20 to 11:10?
Two events overlap and the 10 minute buffer widens them.
Which task does not fit?
deep needs 120 minutes. No gap is that long.
Why do map-1 and map-2 group?
Both URLs give the same document after normalization.
Where does handout.txt go?
documents/handout.txt is occupied, so it gets -2.
Are left:map-1 and right:r-7 merged?
Only after you accept the pair. No record is discarded.

From solution/sample.ics, solution/tasks.json, solution/main.ts, solution/sample.json, download-folder-sort-desk/README.md, samples/input.json, catalog-record-linker/README.md

Tips#

  • An all-day DTEND;VALUE=DATE is exclusive. October 14 ends on 20261015.
  • A file manager must recheck identity right before a move. The plan is not a transaction.
  • ready means accepted merges have no open conflicts. It does not mean every pair was read.
  • GeoJSON uses longitude then latitude order.
  • The bookmark importer reads the JSON folder tree, not browser HTML.
  • Test at least one new input of your own before you integrate a tool.

From calendar-focus-planner/README.md, download-folder-sort-desk/README.md, catalog-record-linker/README.md, field-notes-map-builder/README.md, bookmark-path-organizer/README.md