Faulkner DB: Local Code Maps with Automatic Completion

---
name: faulkner-project-map
description: Operate an existing Faulkner DB local code-mapping script bundle with automatic completion, optional monitoring, status checks and bounded queries.
---

# Faulkner DB: local code maps with automatic completion

Use this skill to operate an existing script bundle in WSL/Bash. Saving this
skill does not install the scripts or a database server.

## Locate the bundle and confirm its interface

Find the folder containing `RUN THIS`, `STOP THIS`, `project_map.py` and the
existing engine/setup helper. Keep those files together. In WSL:

```bash
cd "/path/to/project/Faulkner DB"
./"RUN THIS" --help
python3 project_map.py --help
```

Use Python 3.10+, Git, Bash, `flock` and `tee` for the Linux launcher. Reuse the
existing setup helper and pinned engine. First setup may download dependencies
using uv or venv/pip and need network access. Do not replace it with an unrelated
global install. If copied launchers lack executable permission:

```bash
chmod +x "RUN THIS" "STOP THIS"
```

Read the actual launcher to establish the source target. Some bundles derive it
from their location; others accept a project folder. Similarly named launchers
in different folders can have different arguments and source-selection rules.
Use the actual help as the authority; do not invent options or group names.

## Build once and automatically finish

For an updated bundle whose help confirms build-once as its default:

```bash
./"RUN THIS"
```

Let that process finish. It saves the map, prints `BUILD COMPLETE` and returns
to the prompt automatically. Check the exit code immediately if needed:

```bash
echo $?
```

An agent using a process tool must follow the same process until it exits.
Declare success only after exit code 0, the final completion message and saved
outputs. An intermediate `Map ready` message alone is insufficient. A process
tool returning a running session ID is not permission to launch another copy.

Large code trees can take minutes; output can pause during processing. A pause
alone does not establish a hang. Check `activity.log` where supported. There is
no fixed completion-time guarantee. No manual cancellation is needed for a
successful build-once run, and no background watcher should remain from it.

If an older launcher always watches, inspect the existing one-time index path.
A narrow update should make that path the default, reserve monitoring for
`--watch`, print completion after saved-output checks and propagate failures.
Reuse indexing logic. Do not merely print completion while a watcher continues.

## Optional monitoring and stopping

If help confirms support, run:

```bash
./"RUN THIS" --watch
```

This intentionally remains open after building and updates the map as eligible
source changes. Stop with Ctrl+C or, from another terminal in the same folder:

```bash
./"STOP THIS"
```

Use the existing STOP command that validates its recorded launcher process.
Do not kill unrelated Python processes. Cancellation is not successful build
completion. Confirm the launcher exits and releases its lock before restarting.
Do not remove a lock file to bypass a running process.

## Status, queries and export

Read `project_map.py --help` for required source arguments and supported flags.
For a bundle that does not require an explicit source target, examples are:

```bash
python3 project_map.py status
python3 project_map.py query ExampleSymbol --budget 800
python3 project_map.py index
python3 project_map.py export
```

Replace `ExampleSymbol` with a real symbol in the intended source. Supply a
source folder only when the actual bundle requires it. Do not copy internal
query terms, selectors or group names from another deployment.

Prefer the launcher for builds. Direct Python commands can bypass its locking,
logging and PID/STOP management. Stop monitoring before direct index/export.
Query budgets bound output, not model billing. A small budget can truncate
useful results; a missing result does not establish that code does not exist.

Inspect the status response, not just its exit code: some variants return 0
while reporting that no map exists. If status reports changed source, rebuild
before relying on freshness. Edits after completion can make the map stale.

Use the actual printed output location. Common files are
`graphify-out/graph.json`, an HTML graph and a report; variants can add snapshots
and grouped views. An HTML view may load a visualization library from a CDN.
An exported Cypher file is not evidence of a connected database server.

## Scope and privacy

Inspect source-selection rules before promising coverage. Mapping may cover
only selected Git-visible paths and extensions. Static extraction can miss
dynamic behavior, unsupported syntax and ignored files. Inspect actual source
and runtime before making application behavior claims.

The intended workflow reads code and writes local maps, logs, snapshots, a
possible source mirror and dependency cache. Confirm an unfamiliar bundle's
behavior before running it. Application execution, live database access, paid
model calls, messages and deployment are not needed for this local workflow.

Keep business names, local deployment paths, internal symbols, source inventories,
environment references, source mirrors, graphs and logs private. Public examples
must use placeholders or synthetic source. Code artifacts can be sensitive even
without API keys. Publishing a reusable skill does not authorize publishing the
project-specific runbook or generated data.

## Troubleshooting

- **Already running:** wait for the active launcher or use its matching STOP
  command. Do not bypass its lock with a direct index.
- **Setup fails:** check network, cache permissions and uv/venv/pip prerequisites;
  reuse the existing pinned installer.
- **Extraction fails:** preserve the nonzero result, inspect the error, correct
  its cause and rerun. Existing output may be stale or incomplete.
- **Parser warning:** the file may be partially mapped. The warning alone does
  not prove that the application itself fails.
- **Process stays open:** check for watch mode. Use build-once for automatic exit.

Never call a canceled or failed build successful. A local map does not establish
a passed application build, working live endpoint or external integration.

## Verification of a launcher update

Use a temporary Git repository with synthetic source and the existing scripts
and pinned engine. Observe a real build saving output, printing completion and
exiting 0. Confirm opt-in watching remains active, duplicate starts are rejected,
STOP ends the matching launcher, and PID cleanup completes. Force an isolated
child failure: require nonzero exit without a completion claim. Check shell
syntax and help/argument validation.

Record the actual checks and bundle/version exercised. Publish only generic
test results from synthetic data. These checks validate the exercised local
workflow, not every similarly named bundle or the application being mapped.