PR Lens

PR Lens draws code as visually rich animated diagrams. It can represent diffs, architecture, data flows, and more.

The diff or code is represented as one JSON document (lanes, nodes, edges, ordered flows) and it renders the JSON as an animated SVG

Operating manual

Decide where the diagram lands before you write it: a canvas, or an SVG and a pull request comment. Only a canvas draws payload, the sample request and response on a flow step. A late decision costs another pass through steps 2 and 3.

1. Read the diff. When asked to represent a code change: git diff --find-renames <base>...<head>. The base is the merge base, not the tip of the base branch.

   If not expressing a code diff, read the code to be visually represented

2. Write the document to .pr-lens/graph.json, following references/graph-document.md. references/example.graph.json is valid reference with three lanes, all four delta states, a hero edge, a seven-step flow, a nested drill-down tree and a five-step walkthrough. Read it before you write your first one. It is quicker than reading the reference. If it is going to a canvas, give every flow step (messages) that moves data a payload as you write it. "Sample traffic on a flow step" below says what goes in one. Only a flow step carries one. Flows need the data-flow lens, so an architecture view draws none. A change that touches a migration, an ORM model or a schema file also gets a dataModel, under the data-model lens: the tables it changes, a delta per column, and a relation per foreign key. "Data model" in the reference says what goes in one.

3. Validate, and fix

   bash

   npx @coldtea/pr-lens-cli@latest validate .pr-lens/graph.json

   Fix every failure and run it again. Do not render an invalid document; do not "work around" a failure by deleting the element it names.

4. Render.

   bash

   npx @coldtea/pr-lens-cli@latest render .pr-lens/graph.json

   This draws the light and dark pair, which is what GitHub takes in step 5; the stills attached on their own there are the light half. Render with --theme neutral only for GitLab or Bitbucket, as step 5 says. The SVGs, the manifest and drawn.graph.json land in a directory of their own under .pr-lens/, named after the document's title. The render prints that path, so read it from there. The CLI adds .pr-lens/ to the repository's .gitignore. Do not commit any of it. These files are rebuilt from the diff whenever anyone wants them again. Each SVG is named after its view, the theme and a content hash; manifest.json lists them by lens and view, so read the names from there or from the directory.

   A document with a walkthrough also gets the walkthrough embed, walkthrough-light-<hash>.svg and walkthrough-dark-<hash>.svg: the whole tour as one animated SVG that plays by itself wherever an image shows, flying between the diagrams with each step's caption above. manifest.json lists the two under walkthrough.

   If the user asked for a diagram, an explanation or a picture of the architecture and nothing more, put it on a canvas and hand back the link:

   bash

   npx @coldtea/pr-lens-cli@latest canvas push .pr-lens/<drawing>/drawn.graph.json

   Pass the path the render printed. A bare canvas push finds the drawing when the checkout holds only one; with more than one it lists them and asks which, so always pass the path.

   It prints three links. Give the user the view link, https://prlens.dev/c/{id}: that is the diagram, full screen, every view on one page, and it opens without a login. The edit link, the one ending in #w=…, lets its holder push over the canvas, so leave it out of the reply unless they ask, and never paste it anywhere public. The embed link serves the top view as an SVG for a README.

   Pushing the same document again updates the same canvas, so a follow-up such as "rename that node" or "add the queue" is: edit the document, validate, render, push. While the title stays the same, it renders to the same directory and pushes to the same canvas, so the link does not change. If the push fails, say so and tell them where the SVGs are and which one is the top view.

   A different diagram only needs a different title. It renders into its own directory and pushes to its own canvas, and the first one stays as it was. canvas list shows them all.

5. Attach, when there is a pull request to attach to. That means the user asked you to open a PR, asked for a diagram on one that exists, or you are opening a PR as part of changes made. Otherwise skip this step.

How the diagram gets there depends on the forge. Run git remote get-url origin to see the host before you write a body around a flag that forge may not have.

GitHub. GitHub CLI uploads the diagram with the pull request. Write the body with a Markdown image pointing at the local file, then pass the same path to --attach. gh rewrites the reference to the uploaded asset and keeps the alt text you wrote:

Moves bulk sending off the per-recipient trigger and onto a batch endpoint.
![Walkthrough of this change in six steps: the queue route, the new bulk sender and the retired per-recipient path](.pr-lens/batch-broadcast-sends/walkthrough-light-4f9bd6c1.svg)

gh pr create --title "Batch broadcast sends" --body-file .pr-lens/body.md \  --attach .pr-lens/batch-broadcast-sends/walkthrough-light-4f9bd6c1.svg \  --attach .pr-lens/batch-broadcast-sends/walkthrough-dark-4f9bd6c1.svg

On a pull request that already exists, gh pr edit <number> with the same two flags puts the diagram in the description, and gh pr comment <number> puts it in a comment. Repeat --attach for each diagram the body references.

gh has three rules:

• The reference has to be a Markdown image, ![alt](path). An HTML <img> or <picture> is left as written, and the file is appended at the bottom of the body instead.
• The alt text is the caption a reader without images gets. Say what the diagram shows, in one line.
• --attach arrived in GitHub CLI 2.99. Check with gh --version before you write a body around it.

Attach the walkthrough embed first when the document has one. It plays the tour in the pull request itself, so a reviewer reads the change before reading the diff, with nothing to open. It opens on the top architecture view and tours the rest, so do not attach that view beside it; the two would show the same picture twice. Then a data flow, if the change has a sequence worth following and the tour does not already dwell on it. A document with no walkthrough gets the top architecture view first instead, then the data flow. Leave the rest in .pr-lens/. A body with four diagrams reads worse than one with two, except when the four are really needed to understand the change, as with a complex feature or refactor.

The embed sits on the page's own colour and is drawn once per theme, so a dark-mode reader given the light half sees dark captions on a dark page. GitHub chooses between the two halves only through a <picture> pair, and gh leaves HTML alone, so the pair takes one more step. Pass both halves to --attach, as above: the light one is the Markdown image the body references, and the dark one, referenced nowhere, lands at the end of the body as a Markdown image of its own. Read the body back, take the two https://github.com/user-attachments/assets/... URLs, light first, and replace both image lines with the pair, on one line, since a newline inside the <a> shows as a stray underline:

<a href="LIGHT_URL"><picture><source media="(prefers-color-scheme: dark)" srcset="DARK_URL"><img alt="Walkthrough of this change, in six steps" src="LIGHT_URL" width="870"></picture></a>

gh pr view <number> --json body --jq .bodygh pr edit <number> --body-file .pr-lens/body.md

For a comment, gh pr comment <number> --edit-last --body-file .pr-lens/body.md rewrites the one you just posted. The stills keep the single Markdown image, since each carries its own ground.

GitLab. Nothing uploads the file with the description for you, so upload each SVG to the project first. The response includes the Markdown to paste into the description:

curl -sf --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \  --form "file=@.pr-lens/overview-light-4f9bd6c1.svg" \  "https://gitlab.com/api/v4/projects/<url-encoded-path>/uploads"# → {"markdown":"![overview-light-4f9bd6c1](/uploads/…/overview-light-4f9bd6c1.svg)", …}
glab mr create --title "Batch broadcast sends" --description "$(cat .pr-lens/body.md)"

An uploaded image loads for every reader of the merge request. A raw file URL on a private project does not. The catch is that the attachment URL is the permission: it is unguessable, but anyone who has it can see the diagram, member or not. Tell the user this if the project is private. GitLab strips <picture>, so render with --theme neutral and reference that single SVG. The neutral render has its own background and reads in both light and dark mode. Either half of the light/dark pair looks wrong in one of them. There is no neutral walkthrough embed, so GitLab and Bitbucket get the stills.

Bitbucket. Comments and descriptions are plain Markdown with no HTML, so there are no collapsible sections or theme pairs. Render with --theme neutral here too. Publish the SVGs somewhere durable, such as the repository's Downloads or a canvas, and reference them as ordinary Markdown images.

On any forge where --attach is not an option, publish the SVGs somewhere durable and let the CLI compose the comment instead:

npx @coldtea/pr-lens-cli@latest comment \  --graph .pr-lens/<drawing>/drawn.graph.json \  --manifest .pr-lens/<drawing>/manifest.json \  --asset-base-url https://raw.githubusercontent.com/<owner>/<repo>/<branch>/<dir>

--graph takes the drawing's own drawn.graph.json, not the document you wrote, because corrections change what the diagrams show and the CLI refuses a document its manifest does not describe. --asset-base-url is where you published the SVGs; leave it out and the markdown points at local paths no reader can fetch. The markdown goes to stdout, with each diagram as a <picture> pair; posting it is your business.

Add --target gitlab or --target bitbucket when the comment is not for GitHub, so the composer writes markup that forge can render. GitHub gets <picture> theme pairs and collapsible drill-downs. GitLab gets the same HTML with the single neutral render. Bitbucket gets plain Markdown with the views flattened. With the wrong target, the comment shows its tags as raw text.

If you would rather not author the document yourself, npx @coldtea/pr-lens-cli@latest analyze --base <ref> does steps 1 and 2 by asking a provider — Gemini, OpenAI, or any endpoint speaking /chat/completions — with a key of your own. That is the only path here that needs one.

Answering beside an open canvas

Once a canvas is pushed, you can answer questions about it on the canvas itself. The reader keeps the page open, asks you in the terminal, and your answer plays there: the camera moves step by step, what you name lights up, and each name is a link.

Run this once, when the user wants to talk about a canvas they have open or are about to open. Name the drawing you pushed, the same path as the push:

npx @coldtea/pr-lens-cli@latest canvas open .pr-lens/<drawing>/drawn.graph.json

It opens one browser tab that follows you. Only that tab moves. Anyone else reading the same link sees the canvas as it was. Every command below talks to that tab, and takes the same path as --drawing. Always pass it: a checkout can hold several canvases, and the path says which one you mean.

When the user gives you a link to a canvas you did not push, like https://prlens.dev/c/<id>, open it with the link. This works from any folder, as long as the canvas is not private:

npx @coldtea/pr-lens-cli@latest canvas open --canvas https://prlens.dev/c/<id>

The CLI saves a copy of the drawing to .pr-lens/canvases/<id>.graph.json. Take the ids for your answer from that file. In the commands below, use --canvas <id> in place of --drawing. A private canvas opens only for its owner, after they run npx @coldtea/pr-lens-cli@latest auth login.

When the user says "this", "here" or "what I selected", look first. They clicked a component, dragged a box or picked a part of a drawing in the tab, and you cannot see it:

npx @coldtea/pr-lens-cli@latest canvas look --drawing .pr-lens/<drawing>/drawn.graph.json

It prints JSON: the diagram they are on (diagram.stage, ready to paste into a step), what is on screen (inFrame), what they selected (scope), the answer they have open, and the drawing hung under the canvas (fork), if there is one. Answer about scope when it is set. following: false means they left agent mode: tell them the answer is waiting rather than saying you moved their canvas.

Answer with a JSON file, or - to pipe it in:

npx @coldtea/pr-lens-cli@latest canvas answer .pr-lens/answer.json --drawing .pr-lens/<drawing>/drawn.graph.json

{  "question": "What does push check first?",  "steps": [    {      "heading": "Push checks the token first",      "stage": { "kind": "view", "view": "overview" },      "focus": { "kind": "selection", "nodes": ["canvas-api"] },      "paragraphs": [        {          "parts": [            { "text": "The " },            { "text": "canvas API", "ref": { "kind": "component", "id": "canvas-api" } },            { "text": " refuses a push without the write token, before it draws anything." }          ]        }      ]    }  ]}

• One to four steps. Two is usual. Each step stops on one diagram, in the order a reader should follow.
• heading is a sentence of at most six words: who or what, a verb, what happens. The first step's heading is the answer. To a yes or no question it says yes or no.
• stage and focus work exactly as they do in a walkthrough. Leave stage out for the opening diagram. Light one or two things, not half the diagram.
• A paragraph is one or two sentences and at most 30 words. A second paragraph is for a failure or a risk the first did not name.
• Every place you name carries a ref: component is a node id, message is flowId/messageId, diagram is a view or flow id. Copy ids from the document exactly. Never make one up. The CLI checks every id against the drawing before sending, and the app checks again; a wrong one comes back with the ids that exist.
• When the canvas cannot answer part of the question, say what is missing in cannotTell rather than guessing.

"Take me to X" is a camera move, not an answer:

npx @coldtea/pr-lens-cli@latest canvas show --drawing .pr-lens/<drawing>/drawn.graph.json \  --diagram send-pipeline --focus send-pipeline/enqueue --open send-pipeline/enqueue

--focus takes node ids or flow/message and repeats. --open opens that message's sample payload.

"What's inside X", "expand on X" or "break X down" is a drawing. Write a small graph document of X's insides (up to ten nodes) and hang it under X:

npx @coldtea/pr-lens-cli@latest canvas fork .pr-lens/inside-x.json --from x --drawing .pr-lens/<drawing>/drawn.graph.json

The sketch can leave out schemaVersion, kind and provenance; they come from the canvas.

When the question needs the diagram itself changed (a missing component, a wrong arrow), edit the document, validate, render and canvas push as usual. The open tab reloads onto the new revision by itself.

After answer, show and fork, the CLI says where the reader is. If it says they stepped out, tell the user the answer is waiting in their Questions list, and that / opens it.

The pull request body, when there is one

A reviewer should understand the change before reading the diff, so the diagram goes where they look first: the description, not a trailing comment. Open with one sentence on why the change exists, then the walkthrough embed, or the architecture diagram when the document has no walkthrough, then whatever proves the change works, such as a screenshot of the result or a recording of the interaction. Use one visual per idea. A diagram that needs a paragraph of explanation has a document problem; go back to step 2.

What makes a document worth reading

• Include what did not change. A diagram of only the changed nodes says nothing about blast radius. The unchanged neighbours a change touches are the context; mark them delta: "unchanged".
• Lanes are the reader's mental model (a runtime, a tier, a boundary), not the folder tree.
• One hero edge, two at the outside: the connection the change is really about.
• Add a flow only when there is a sequence worth animating. One good flow beats three thin ones.
• Attach file refs: they become the permalinks a reviewer clicks.
• There is no findings lens. PR Lens is the comprehension layer, not another review bot. There is no field for a bug, a risk or a security note, and a document that invents one is rejected rather than trimmed.

Choosing architecture views

Treat architecture views as a C4-inspired decision tree, not a checklist. One useful view is enough for a small change. Start with system context when the change affects a user, an external system or a system boundary. Use a container view for the affected applications, services, jobs, data stores and runtimes. Add a component child only when an affected container's internals matter. Do not add code-level views by default.

Every child moves down one level and covers a materially narrower scope. Skip empty, repetitive or speculative levels, and do not infer architecture from folder names alone. Two views should not carry substantially the same nodes and edges. Keep the unchanged direct neighbours that explain blast radius.

Keep data-flow views as separate roots rather than nesting them in the architecture tree. Set defaultOpen: true on the highest useful architecture view. Lower levels should normally keep the default, false.

Scope a child view by its nodes and edges, and leave lanes out. A lane in a scope draws every node in that lane, wanted or not, and the lanes your nodes sit in are drawn anyway.

Writing a walkthrough

A walkthrough is a short guided tour of the diagrams. It has two to twelve steps. Each step shows one diagram, points at one part of it, and says a few words about it. A canvas plays it, and the reader scrolls through it.

The contract leaves a walkthrough optional. Write one anyway for anything that is not trivial: more than one diagram, a diagram with several changed parts, or any flow. Skip it only when the document is one small diagram whose single step would just repeat the title.

Aim for three to nine steps.

A walkthrough is the fastest read of a pull request. Each step is one change: something added, changed, removed or moved, in the order a reviewer needs it. A step is never a description of the diagram.

What counts as a step: a behaviour change, an API change, an architecture change, a data-flow change, or an addition. Unchanged parts appear only where a step needs them to make sense. The headline change is step one. The last step is the last real change, staged and focused like every other, such as the old path going away or the one thing a person now sees. Do not end on a recap of everything touched. The reader already saw the whole picture when the canvas opened.

"walkthrough": {  "steps": [    {      "id": "four-batch-calls",      "heading": "Postmark now gets 500 emails per call",      "body": "One call per batch, and Postmark answers with a result for each message.",      "stage": { "kind": "flow", "flow": "send-pipeline" },      "focus": { "kind": "selection", "messages": ["batch-post", "batch-results"] },      "detail": {        "text": "sendBroadcastBulk posts each batch to Postmark and reads the results back.",        "cites": [          { "text": "sendBroadcastBulk", "ref": { "kind": "node", "node": "send-broadcast-bulk" } },          { "text": "posts each batch", "ref": { "kind": "message", "flow": "send-pipeline", "message": "batch-post" } },          { "text": "Postmark", "ref": { "kind": "node", "node": "postmark" } }        ]      }    },    {      "id": "old-path-goes-dark",      "heading": "processBroadcast and sendSingleEmail removed",      "body": "sendBroadcastBulk does their job for whole batches.",      "stage": { "kind": "view", "view": "retired-path" },      "focus": { "kind": "selection", "nodes": ["process-broadcast", "send-single-email"] }    }  ]}

Each step has:

• heading: the thing and what happened to it, up to 48 characters, in sentence case. Build it from change words: added, removed, replaced, now, moved, split. If a heading could have been true before the pull request, it is not a change heading.
• body: one line under the heading, up to 140 characters, on what the change means for behaviour: what happens now that did not before, or what stops happening, with the numbers when they matter. Not a restatement of the heading, and not a description of the code. A heading with no body reads as unfinished, so the body is required.
• stage: which diagram to show. A document can have several diagrams: its views (the drill-down diagrams) and its flows (the sequence diagrams). { "kind": "view", "view": "overview" } shows the view called overview. { "kind": "flow", "flow": "send-pipeline" } shows the flow called send-pipeline. Leave stage out and the step uses the diagram the reader is already on. Stage each step on the smallest diagram that draws what it names, usually a child view or a flow.
• focus: what to zoom in on inside that diagram. { "kind": "all" }, the default, means the whole diagram. A selection means "just these things": name nodes, edges or flow steps (messages) by id, and the camera zooms to them while everything else dims. Give every step a selection on what its change touched, so the veil lights the change. See "Lighting one change" below for how much one step can name.
• detail: optional. A second sentence under the body, with links into the diagram. See "Links under a step" below.

Write every word for a smart twelve-year-old: short common words, one idea per line, active voice, things named as the diagram names them, numbers as digits. If a line needs a second read, rewrite it. Words like leverages, orchestrates, asynchronous pipeline and fan-out never belong in a step. This holds in whatever language the document is written in.

The same three steps, written well and written badly. Heading first, then the body after the slash:

Lighting one change

The canvas cuts one box around everything a focus names and lights every card inside that box, named or not. Two things far apart light everything between them, and the reader can no longer tell what the step is about. How much a focus can name depends on the diagram under it:

• On a view that draws four cards or fewer, up to three nodes and the edges between them.
• On a bigger view, one node.
• On a flow, up to three flow steps that follow one another. Steps with a gap between them light the steps in the gap.

Count a view's cards before you name a second node: the nodes its scope names, plus both ends of every edge it names. When a step is about two or three nodes (one replacing another, a pair removed together) and its view draws five or more, add a child view of only them and stage the step there, or focus the flow step between them. Name an edge only when the edge is itself the change. Never name a lane in a focus, because it lights every card in that lane.

When a change needs more than one focus can hold, split it into steps, each with its own heading, body and focus. A step that names a page, its route and two services the route calls lights half the diagram. Write one step on the page, one on the route, and one on the flow step that matters.

Links under a step

The body has no links. To let the reader jump to a part of the diagram, add a detail under the body.

A detail is one or two sentences, up to 240 characters. It says which parts do what the body describes, and it uses the names on the diagram. Its cites turn words in that sentence into links.

• A cite's text is copied letter for letter from the detail's text.
• A cite's ref says where the link goes. A node is { "kind": "node", "node": "postmark" }. A flow step is { "kind": "message", "flow": "send-pipeline", "message": "batch-post" }. A whole diagram is { "kind": "view", "view": "overview" } or { "kind": "flow", "flow": "send-pipeline" }.
• List the cites in the order the sentence says them. Two cites cannot use the same words. A detail has one to eight cites.
• Copy every id from the document. Never make one up.

A click on a node or a diagram moves the camera there. A click on a flow step also opens its sample payload, when it has one.

Do not cite files. A canvas you push has no pull request behind it, so a file link has nothing to open and shows as plain words.

Leave the detail off any step where it would only say the body again.

Keep consecutive steps on the same stage together. Every change of stage flies the camera across the canvas, so a tour that alternates between two diagrams spends its time travelling.

The validator checks:

• Every id you name exists in the document. A flow step you name must belong to the flow the stage shows, because flow step ids are only unique inside their own flow.
• messages needs a stage that shows a flow. Leave it out when the stage is an architecture view.
• Step ids are unique within the walkthrough. Two steps minimum, twelve maximum.
• Every cite's words are in its detail's text, in the order the cites are listed. The node, flow step, view or flow it points to exists in the document.
• A stored map never carries a walkthrough. A map describes the system; a walkthrough tells the story of one change.

The field arrived with contract 0.1.1. A CLI older than 0.4.0 does not know it and rejects the whole document as an invented field, so validate with a current one. detail is newer still. If validate rejects it as an unknown field, the CLI is out of date.

Sample traffic on a flow step

A flow step can carry a payload: what travels on it. Only the canvas draws it, in the rail that opens when a reader clicks a step. Nothing in an SVG or a pull request comment changes. Write it when the document is going to a canvas (step 4, canvas push) and leave it out otherwise. Six payloads on the reference document add half its length again, so this is not a field to fill by default.

On a canvas document, add it to a step that moves data: a request body, a job record, a query, a result. Leave it off a step that only signals, such as a trigger with nothing attached.

{  "id": "batch-post",  "from": "send-broadcast-bulk",  "to": "postmark",  "label": "POST /email/batch",  "kind": "sync",  "delta": "added",  "repeat": 4,  "payload": {    "request": {      "type": "EmailBatch[500]",      "shape": "Email[]  // max 500\nEmail = { From: string; To: string; Subject: string; HtmlBody: string; MessageStream: \"broadcast\"; Metadata: { campaignId: string; batchId: string } }",      "sample": [        {          "From": "news@example.com",          "To": "ada@example.com",          "Subject": "The batching issue, fixed",          "HtmlBody": "<!doctype html><html><body>…",          "MessageStream": "broadcast",          "Metadata": { "campaignId": "cmp_0001", "batchId": "b_0001" }        }      ],      "before": [        {          "From": "news@example.com",          "To": "ada@example.com",          "Subject": "The batching issue, fixed",          "HtmlBody": "<!doctype html><html><body>…",          "Metadata": { "campaignId": "cmp_0001" }        }      ],      "source": { "path": "tests/fixtures/postmark-batch.json" }    },    "response": {      "type": "BatchResult[500]",      "shape": "SendResult[]  // one per Email, same order",      "sample": [{ "ErrorCode": 0, "Message": "OK", "To": "ada@example.com", "MessageID": "b7fa5c1e-…" }]    }  }}

A payload has a request side, a response side, or both. Each side has:

• type: the name a reader of the code would recognise. Put the count in it when the step carries a collection: EmailBatch[500], not EmailBatch. Write { "type": "void" } for a side that carries nothing, such as the answer to a fire and forget call.
• shape: the type signature as text, taken from the code's own types. Up to 2048 bytes.
• sample: one exemplar instance after the change, written inline as JSON. It is a JSON value, not a JSON string: "sample": [{ "To": "ada@example.com" }], never "sample": "[{\"To\": ...}]". A string here is rejected. Every key once, one element in any array, long strings cut with an ellipsis. At most 8 levels deep and 4096 bytes once serialised. The parser refuses a sample over either cap rather than trimming it.
• before: the same exemplar as it was before the change, when it differs. Same rules as sample, and it needs a sample to differ from.
• source: the fixture or type the shape and sample came from, as a file reference. It becomes the permalink.

Use placeholder values: ada@example.com, cmp_0001. Never copy a value from a fixture that could belong to a real person or unlock something, even in test data.

Do not write changedPaths. The paths that differ between before and sample are worked out when the document is stored. A list you write is discarded.

The field arrived with contract 0.2.0. A CLI built before it rejects the whole document as an invented field, so validate with a current one.

What the validator will catch

Read references/graph-document.md before writing. The four failures that account for nearly everything:

Seven rules cannot be expressed in JSON Schema and are checked only by the parser, so structured output alone does not make a document valid: referential integrity, a line range that ends before it starts, a self message whose endpoints disagree, a patch whose two commits are the same, more views than a render manifest could describe, a walkthrough step focusing flow steps the diagram on its stage does not draw, and sample traffic past its depth or byte caps. Always validate.

Fixing a map instead of writing one

When someone says the diagram is wrong (a node is misnamed, a folder should not be on it, something sits in the wrong lane), do not edit the generated document. It is regenerated on every run. Write the correction into .github/pr-lens.yml, which is an overlay applied over fresh inference every time:

schemaVersion: 0.3.1map:  rename:    - match: functions/src/broadcast/sendBroadcastBulk.ts      to: Broadcast sender  exclude:    - "**/*.test.ts"  lane:    - match: packages/broadcast-lib/**      lane: functions

references/config.md has the full format and the recipes. Validate it the same way: npx @coldtea/pr-lens-cli@latest validate .github/pr-lens.yml.

A match beginning with id: addresses one node exactly; anything else is a path glob matched against a node's file paths. Prefer the glob, because it keeps holding when the next run names the node differently. A lane pin may name a lane the document never declared: the band is created, and takes the id for its label, so give it one a reader would want to see.

pr-lens render says so when a correction matched nothing, which is how a config that has drifted, because the file it named moved or was deleted, becomes visible instead of quietly doing nothing.

Reference pages

npx @coldtea/pr-lens-cli@latest skill references prints all three pages below. Each page starts with a heading that holds its name, so you can find the one this manual points you to.

The same document ships as postmark-refactor.graph.json in @coldtea/pr-lens-schema, and the JSON Schema the validator enforces is published at https://unpkg.com/@coldtea/pr-lens-schema/json-schema/graph-doc.schema.json. Neither is something you need to fetch to write a document.