Audit Broken Documentation Links with a Read-Only Agent Brief

What you need before you start

This is a manual audit you run and check. Cue supplies voice capture and optional Agent help with the material you give it. It does not follow from having Cue installed that an Agent can read your repository, open your intranet, crawl a site or edit a file.

Before you begin, have all of the following:

• Cue installed and Dictation working. Confirm microphone access and any input or accessibility permission Cue asks for on your platform. Use the shortcut shown in your Cue Settings rather than a key combination you read somewhere. The Dictation tutorial covers the focus, recording-state and insertion checks this guide assumes you already do.
• An editable scratch note. Start in a scratch field, not a shell prompt or a document that auto-publishes. Review the brief before submitting it anywhere.
• A folder you can delete. The exercise below creates seven small files. Put them somewhere disposable. Do not build the fixture inside a real repository where a stray git add . would commit it.
• A terminal you already use, or a text editor that displays line numbers. You can inspect every file manually; shell execution is not required.
• An Agent you have connected yourself. Your installed Cue may show Cue, Claude, Codex and Gemini in its Agent selector. Visible in a list is not the same as connected, signed in, permitted or able to read your disk. Confirm this in your own copy before you assume a report describes a real read of your files.
• Nothing confidential in scope. No credentials, tokens, private URLs or customer documentation. The exercise is entirely fictional so you can practise without any of that.

One decision belongs to you, not to any Agent: what counts as broken. Decide before the audit whether a missing anchor, an unreachable external site, a case-mismatched filename or a link inside a code sample counts as a defect in your project. An audit without that definition produces a list nobody can act on.

Practice: the Orchid Notes docs fixture

Orchid Notes is a fictional note-taking app invented for this exercise. The files below are practice material, not Cue documentation and not a real project. External addresses use the reserved .invalid suffix. That is not a network sandbox: do not fetch these addresses, and keep network access disabled for the audit. Report them as unchecked rather than assigning a status you did not verify.

Create a folder named link-audit-fixture and put these seven files in it. Keep the paths exactly as shown — several of the planted defects depend on the directory layout.

index.md

# Orchid Notes documentation

Orchid Notes is a fictional note-taking app used only for this exercise.

- [Getting started](./getting-started.md)
- [Install guide](./guides/install.md)
- [Troubleshooting](./guides/troubleshooting.md)
- [API reference](./reference/api.md)
- [Uninstall guide](./guides/uninstall.md)
- [Release notes](./CHANGELOG.md)
- [Support mailbox](mailto:support@example.invalid)

![Architecture diagram](./assets/architecture.png)

getting-started.md — note that lines 12 to 14 are a fenced code block showing link syntax, not a link the reader can follow:

# Getting started

Read the [install guide](./guides/Install.md) first, then open the
[API reference](./reference/api.md).

For offline setup, see [offline mode](./guides/install.md#offline-mode).

The legacy handbook lives at https://example.invalid/orchid/legacy-handbook.

Downloads are named like this in our release template:

```markdown
[Download the installer](./dist/orchid-1.2.3.dmg)
```

See [release notes]() for the full history.

CHANGELOG.md

# Release notes

## 1.2.0
Adds the sync panel. See [sync settings](./reference/api.md#sync-settings).

## 1.1.0
Fixes the export bug described in [troubleshooting](./guides/troubleshooting.md).

## 1.0.0
First release. The old notes format is documented in
[the legacy handbook](./guides/uninstall.md).

guides/install.md

# Install

## Requirements

## Desktop install

Return to the [documentation home](../index.md) or continue to the
[API reference](../reference/api.md).

If the installer fails, read [troubleshooting](./troubleshooting.md).

guides/troubleshooting.md

# Troubleshooting

## Export produces an empty file

Check the [install requirements](./install.md#requirements).

## Sync never finishes

See the [sync notes](../reference/api.md#sync-settings) and the
[status page](https://example.invalid/orchid/status).

Still stuck? Open the [support checklist](../support/checklist.md).

reference/api.md

# API reference

## Sync settings

## Export endpoint

Back to [home](../index.md).

assets/diagram.png — create a placeholder file with any content. Its name matters; its contents do not. One line of text is enough.

Write the expected broken-link list before you run anything

This is the step that makes the exercise worth doing. Write the answer key first, then see what the report says. If you look at the report first, you will find yourself agreeing with it.

Planted defects — seven occurrences, six distinct targets:

Decoys — six things that must not appear in the broken list:

D-2 and K-6 expose two reporting failures. A report that merges D-1 and D-2 without retaining both source locations has lost a file you need to review. A report that lists K-6 as broken has either guessed or made a request you did not approve.

Dictate the brief and choose your route

1. Build the fixture folder and save your expected list somewhere separate. Do not paste the answer key into the Agent's context; you are testing it, and a brief that contains the answers tests nothing.
2. Open a blank scratch note and focus its text field. Start Dictation using the shortcut in your Cue Settings and confirm the recording state before you speak.
3. Speak the audit goal and its boundary. Something like: "Audit the markdown files in this folder for links that point at files or headings that do not exist. Report file, line and exact target for each one. Do not fetch any external address. Do not edit any file. List anything you did not check separately." Stop with your configured control, wait for processing, then read the inserted text.
4. Correct the transcription before it goes anywhere. Paths, extensions, capital letters and the word not deserve an explicit proofreading pass: changing one can change the task. Copy link-audit-fixture, ./guides/install.md and similar strings from the source rather than dictating them. See dictating exact technical terms if identifiers keep changing on you.
5. Pick one of three routes, and know which one you are on. They are not interchangeable.
   • Dictate into the Agent you already use. Focus the composer of the coding Agent in your terminal or editor and dictate or paste the checked brief. Cue is providing the text; the Agent's own permissions decide what it can read.
   • Select an external Agent inside Cue. If your installed Cue offers Claude, Codex or Gemini as an Agent, confirm that route's connection, sign-in, project and permissions first. Do not assume it inherits your terminal's working directory or an earlier conversation.
   • Use Cue's own Agent with a chosen model. Cue's model selector chooses a model. It does not grant file access, shell access or network access, and it does not connect an external Agent. If you are not certain the Agent can read the folder, take route four below instead.
6. Manual fallback: open the six Markdown files yourself and paste the non-sensitive contents, with file names and line numbers, into your Agent. It can review that supplied text, but cannot verify your disk from the paste alone. Label any report as a text review, not a filesystem audit.
7. Read the report against your expected list, not against your memory of the fixture. Mark each planted defect found or missed, and each extra claim as confirmed or invented.
8. Delete the fixture when you are done, or keep it deliberately as a regression exercise for the next Agent or model you evaluate.

Copy a read-only audit brief

Replace the bracketed fields. Do not leave placeholders in a real task, and do not widen the scope to make the run succeed.

Task: Audit documentation links. Read-only. Do not edit, create, move or delete any file.
Scope: [absolute path to link-audit-fixture], markdown files only, no subdirectories outside it.
Definition of broken, for this audit:
- a relative link or image whose target file does not exist
- a link to a heading anchor that does not exist in the target file
- a link with an empty target
- a target whose spelling differs from the file on disk, including capitalisation
Out of scope, list separately and do not call broken:
- external http and https addresses. Do not request them. Approved list: [none]
- mailto and tel links
- links that appear inside fenced code blocks, which are examples, not links
For every finding return: file path, line number, the exact link target as written,
which of the four categories above it falls into, and the evidence you used.
If you did not open a file, say so. If you inferred rather than checked, say so.
List every link you could not classify in an "unchecked" section with the reason.
Do not propose edits yet. Do not run any command that writes. Do not fetch anything.
Report only. Wait for my next instruction.

The "approved list: none" line is deliberate. This exercise has no reason to fetch its fictional external addresses. A later audit of real external links needs a separately approved list and a tool whose network access is limited to that list. A read-only request can still disclose an address or reach a private, authenticated or rate-limited system; read-only does not mean offline. Never hand an Agent credentials merely to make this exercise pass.

Grade the report, do not just read it

Worked example — synthetic, not an Agent run: suppose a report lists D-1, D-2, D-3, D-6 and D-7, also flags K-5, and places K-6 under unchecked. It found five planted defects, missed D-4 and D-5, and produced one false positive, K-5. Leaving K-6 unchecked is correct for this offline scope. Copy these three categories into your own review instead of accepting a bare “audit complete”.

Take the Agent's report and your answer key and go through both in one pass. Three columns, filled in by you:

Then check the files themselves against a baseline saved outside the Agent's writable scope before the audit. Compare the file inventory and content hashes. In a repository, inspect git status and git diff, including untracked and ignored files where relevant. Neither a clean Git status nor unchanged modification times proves that no temporary write occurred or that no data was read or sent. Those checks establish final file state only; enforcing the read-only and offline boundaries requires tool permissions, with invocation records as supporting evidence. An Agent saying it made no changes is not evidence that it made no changes.

Count what you find as counts: how many of the seven were named, and how many extra claims were invented. Do not convert it into a score, a percentage or an accuracy figure. Seven planted defects in one fictional folder cannot support any of those, and a number like that would travel further than the evidence behind it.

A report that misses D-4 and D-5 is not useless — it is a report whose scope you now know. The point of grading is to learn which categories that particular Agent, on that particular route, actually checks, so you know what you still have to check yourself.

Limitations

• This audits a folder of markdown files. It does not establish the state of a rendered site, redirects, links generated by templates, links inside HTML attributes, or links assembled at build time. Those need a crawler and a different kind of permission.
• It does not check external links at all. By design. The fictional .invalid addresses stay unchecked; their reserved suffix does not prove that a tool made no network request. A separate real-link audit needs an approved scope.
• A clean run does not mean the documentation is correct. A link can resolve to the wrong page, and a page can exist while being out of date. Link existence is the cheapest property to test, not the most important one.
• A text search is not a Markdown parser. A naive search can report the fenced example as a broken link and miss bare URLs or reference-style links. Check the rules of your documentation renderer before treating a match as a defect.
• Filesystem behaviour differs. A file-existence check for D-4 depends on whether your local filesystem is case-sensitive. The same audit on a Mac and on a Linux CI runner can legitimately disagree.
• No built-in link checker is verified here. This is a method for capturing an audit brief by voice and bounding what you ask an Agent to do with it, not an inventory of Cue's capabilities. Whether a given Agent can read your folder at all is something you confirm in your installed version.
• One fixture is one sample. Grading well here does not predict behaviour on a large real repository, a different model or a different route.

Recover when a step goes wrong

For a problem with Cue itself, use Contact Cue support with your platform, Cue version, mode and a redacted example. Do not send private documentation, repository contents or tokens.

Questions worth answering before you scale this up

Why plant the defects instead of running this on real docs first? On unfamiliar documentation, "found nothing" can hide "checked nothing". A fixture gives you a known answer before the run; real repositories still need their own coverage checks.

Should I keep the fixture after grading once? It is cheap to keep and useful whenever you change model, Agent or route. Keep it outside any repository that gets published, and keep the answer key in the same place so the two do not drift apart.

Can I just ask the Agent to fix the broken links? Repair is a separate, authorised task with its own review, and most of these defects have more than one correct fix. uninstall.md could mean write the missing page, or remove the link, or point it somewhere else — that is an editorial decision. Grade the audit first; propose repairs second; apply them yourself.

Which model should I use? Start with what the route can actually read, not just the model name. A model with no file access should disclose that limitation. It may instead produce a plausible report about files it never opened; this exercise helps expose that failure. A model that honestly reports "not checked" has not completed the audit, but it has not fabricated a result either.

Sources and related workflows

The fixture, its defects and the illustrative Agent behaviour described above are exercise material. No part of this guide claims a measured outcome for Cue or for any Agent. This published version uses a manual inspection exercise, not an executable link-checker script. Your installed Cue version, its visible controls and your Agent's permissions take precedence over anything written here.

• Cue Dictation tutorial: focus, recording state and insertion checks.
• Cue Voice Agent tutorial: explicit context and review before action.
• Cue with coding Agents: the difference between dictating into a tool, selecting an external Agent, and using Cue's Agent with a chosen model.
• Review a code change with Codex: the same evidence discipline applied to a diff instead of a docs tree.
• Dictate exact technical terms: keeping paths, versions and identifiers intact.
• Turn selected context into a finished task: what to do once an audit has produced work you intend to act on.