# Audit And Tooling

## Audit Purpose

The `audit/` directory is the persistent human feedback surface. It lets a user select or quote a passage, attach a severity and comment, and have the agent later resolve that feedback without losing it in chat history.

Feedback may come from:

- manual Markdown files
- the bundled Obsidian audit plugin in `plugins/obsidian-audit/`
- the bundled local web viewer in `web/`

## Audit Layout

```text
audit/
  20260425-143022-example.md
  resolved/
```

Open feedback lives directly in `audit/`. Processed feedback moves to `audit/resolved/`. Do not delete feedback history unless the user explicitly asks.

## Audit File Shape

Preferred frontmatter:

```yaml
---
id: 20260425-143022-a1b2
target: wiki/concepts/example.md
target_lines: [45, 52]
anchor_before: "text before selection"
anchor_text: "selected text"
anchor_after: "text after selection"
severity: warn
author: user
source: obsidian-plugin
created: 2026-04-25T14:30:22+08:00
status: open
---
```

Body:

```markdown
# Comment

The selected claim is stale. Source X says...

# Resolution

<!-- Filled when processed. -->
```

Severity order: `error`, `warn`, `suggest`, `info`.

## Audit Processing

1. Run `python scripts/audit_review.py <wiki-root> --open` when the standard layout fits.
2. Read the feedback file and target page.
3. Locate the selected passage with `target_lines`, `anchor_text`, and surrounding context.
4. Decide: accept, partially accept, reject, or defer.
5. Apply the smallest useful edit to the target page.
6. Append a resolution explaining what changed and why.
7. Change status to resolved if the vault uses that field.
8. Move the file to `audit/resolved/`.
9. Log the resolution.

For stale anchors, do not silently drop the feedback. Re-anchor, ask the user, or defer with an explicit note.

## Bundled Feedback Stack

### `audit-shared/`

Shared TypeScript utilities used by both feedback surfaces:

- audit schema
- anchor extraction and matching
- id generation
- YAML serialization

Use this when modifying the plugin or web viewer so both tools continue to write compatible audit files.

### `plugins/obsidian-audit/`

Obsidian plugin workflow:

1. Build the shared library if needed.
2. Build the plugin.
3. Link or copy it into the user's vault.
4. Enable the plugin in Obsidian community plugins.
5. Select text in a note and run the audit command to create an anchored feedback file.

Typical commands from the source stack:

```bash
cd audit-shared && npm install && npm run build
cd ../plugins/obsidian-audit && npm install && npm run build
npm run link -- "/path/to/vault"
```

Only run dependency installation when the user wants the plugin built locally.

### `web/`

Local web viewer workflow:

```bash
cd audit-shared && npm install && npm run build
cd ../web && npm install && npm run build
npm start -- --wiki "/path/to/wiki-root" --port 4175
```

The viewer renders Markdown, wikilinks, Mermaid, and KaTeX, shows wiki navigation, lists open audits for the current page, and lets the user select text to submit feedback.

Treat it as a local personal tool. If a port is in use, use another local port.

## Lint Checks

Run `python scripts/lint_wiki.py <wiki-root>` when the standard layout fits. Otherwise manually inspect:

- dead wikilinks
- orphan pages
- missing index/map entries
- duplicate topics or entities
- pages that should be split
- missing source sections
- stale claims
- unresolved contradictions
- malformed frontmatter
- broken embeds or attachment links
- malformed audit files
- audit targets that no longer exist

## Obsidian Setup

Recommended settings:

- Attachment folder path: a stable local assets folder, often `raw/assets/`.
- Download attachments hotkey: bind Obsidian's attachment download command for clipped web pages.
- Graph view: use it to spot hubs, clusters, and orphan pages.

Useful plugins:

- Obsidian Web Clipper for article capture.
- Dataview or Bases for structured views over frontmatter.
- Canvas for visual maps.
- Marp for turning wiki pages into slide decks.

## Search

Small wikis can be navigated through the index/map. Larger wikis may use local search tools such as qmd.

Search is only for locating candidate pages. The agent should still read the relevant pages before answering.