# paranco, operating notes for an agent

You are reading this because you may be asked to change paranco, or to read what it lifted.
Read README.md first, then docs/integration.md. The points below are the ones an agent most often
gets wrong.

Source: https://github.com/nerln/paranco. macOS 14 or later, Swift 6, MIT.

## What paranco is

paranco holds Full Disk Access and copies files one way, along routes, from a folder macOS protects
into an ordinary folder. Today it has one source, the Voice Memos library. Sources are a list compiled
into the binary, in Sources/ParancoCore/Source.swift. A route names a source by identifier, never by
path. Routes are in ~/Library/Application Support/paranco/routes.json, and the agent log is beside them.

## When a library looks empty or refused

- There are three answers: readable with a count, refused, and missing. Readable with zero files is a
  real zero. Refused means macOS will not let this process list the folder. Missing means there is no
  folder at that path. Ask `paranco check` or the window which answer you have.
- Do not give Full Disk Access to an interpreter, a terminal or a runtime to get past a refusal. macOS
  would grant it to everything they load. Use a route, and read its destination instead.
- `paranco check`, run from a terminal, says refused on a protected folder even when Paranco.app has
  the grant. The grant belongs to the app, not to the terminal. This is expected.

## Do not

- Do not write routes.json by hand, and do not put a path in `sourceID`. A route whose `sourceID` is a
  path lifts nothing. An old entry that named its source by path is kept only if the path is one of
  the listed folders. Otherwise it is dropped.
- Do not add a source to Source.swift unless the operator asks. A new source needs a rebuild and a new
  Full Disk Access grant. That is a decision for a person.
- Do not run `paranco lift` for a protected source from your own session. The access is charged to
  your process and is refused. Ask the operator to choose Route > Lift now in Paranco.app.
- Do not run build.sh or any script that installs the app in a session that only changes documents or
  tests. A new build has a new signature, and the grant has to be given again.
- Do not point a route at a folder that is an encrypted volume while the volume is closed. The path is
  then an empty folder on the disk, and files written there are not encrypted.

## Commands

- `swift test` runs the core's tests. `swift test --filter ContractTests` runs the tests for the file
  format that other programs read.
- `swift build -c release --product paranco` builds the command line.
- `paranco sources`, `paranco routes`, `paranco add <source-id> <folder>`, `paranco remove <name>`,
  `paranco check [<folder>]`, `paranco lift [<name>]`, `paranco agent status`.

## Facts to check before you change code

- A destination must be a real folder inside the home folder, outside ~/Library, on this Mac's own
  disk. No symbolic link may be on its path. See `Destination.validate`.
- A file is copied when its name is new or its size differs. A file whose size is still changing is
  skipped until it stops. See `Lift.run`.
- Nothing is written to a source. The copy goes into a fresh file that is renamed into place. See
  `Lift.copySafely`.
- There is no network code. Check with `grep -rn "URLSession\|URLRequest" Sources/`.
- The agent runs every five minutes, and once when it is loaded. It is installed from the window, not
  from the command line. `paranco agent status` says whether it is installed.