BRAINIALL PDF Context for Spec Kit

A BRAINIALL-maintained community extension for GitHub Spec Kit. It converts one explicitly selected PDF into a separate, reviewable context bundle: Markdown, structured page evidence, and a hash-based receipt.

The extension never scans for PDFs, never runs as a hook, and never changes spec.md, plan.md, tasks.md, or source files. A conversion requires a named PDF, a new output directory, and confirm=yes.

Install

Requirements:

• Spec Kit >=0.14.3,<1.0.0
• Python 3.11 or newer
• A BRAINIALL API key

Install the v1.0.1 release into an initialized Spec Kit project:

specify extension add brainiall-pdf-context \
  --from https://github.com/fasuizu-br/spec-kit-pdf-context/archive/refs/tags/v1.0.1.zip

Confirm registration:

specify extension list

Configure the credential

Create a key at app.brainiall.com and export it only in the process environment:

export BRAINIALL_API_KEY="your-key"

Do not put the key in command arguments, extension.yml, project configuration, committed files, screenshots, logs, or generated artifacts.

Use

In Codex skills mode, invoke the registered skill:

$speckit-brainiall-pdf-context-convert pdf="docs/product-brief.pdf" output_dir=".specify/pdf-context/product-brief" confirm=yes page_range=1-20

In command-based integrations, invoke:

/speckit.brainiall-pdf-context.convert pdf="docs/product-brief.pdf" output_dir=".specify/pdf-context/product-brief" confirm=yes page_range=1-20

Invocation syntax varies by Spec Kit integration. specify extension list shows the registered command for the current project.

The command first performs a local dry run. It sends the selected PDF only after the exact confirm=yes token is present. The client makes exactly one request to:

https://api.brainiall.com/v1/document/pdf-to-markdown/file

There is no endpoint override, redirect following, background call, or automatic retry.

Direct client use

After installation, inspect the plan without network access:

python3 .specify/extensions/brainiall-pdf-context/scripts/pdf_context.py \
  --pdf docs/product-brief.pdf \
  --output-dir .specify/pdf-context/product-brief

Make the one confirmed request:

python3 .specify/extensions/brainiall-pdf-context/scripts/pdf_context.py \
  --pdf docs/product-brief.pdf \
  --output-dir .specify/pdf-context/product-brief \
  --confirm-send

Add --page-range 1-20 to process one page or an inclusive page range.

Output contract

output_dir must not exist before the run. After a successful response, the client reserves that directory with an exclusive create and writes:

File	Contents
document.md	Non-empty Markdown returned by BRAINIALL
pages.json	Normalized page count, source envelope, response metrics, and per-page items when returned
receipt.json	Version, fixed endpoint, source tag, UTC timestamp, page count, request ID when available, and SHA-256 hashes

The directory is mode 0700; files are created with O_EXCL and mode 0600. If any file write fails, the newly reserved directory is removed. Existing output is never replaced. The directory may be briefly visible while its three files are being written, so the contract is exclusive and fail-clean rather than an atomic three-file visibility guarantee.

The receipt intentionally excludes the API key and document text. It proves a technical conversion, not an independent buyer, payment, settlement, or revenue.

Security and privacy boundaries

• Only the explicitly selected, project-contained regular PDF is read and uploaded.
• A symbolic link used as the selected PDF itself is rejected. Intermediate symbolic-link components are resolved and accepted only when the resulting regular file remains inside the project. Output components are likewise resolved and confined; the output leaf itself must not already exist, including as a dangling link.
• Files outside the project, non-PDF signatures, and files larger than 25 MiB are rejected before network access.
• BRAINIALL_API_KEY is accepted only from the environment and never enters the multipart body or output.
• Request identifiers are accepted only from three named headers or three named JSON fields, must match a narrow identifier grammar, and are dropped if they contain the API key.
• Credentials are not forwarded because HTTP redirects are rejected.
• The fixed metered POST is attempted once. Failures are never retried automatically.
• Output under specs/ or .specify/extensions/ is rejected, preventing silent mutation of specifications or the installed extension.
• The client caps the response at 50 MiB and commits the bundle only after validating JSON, Markdown, and pages.

Review current BRAINIALL pricing and data-handling terms before processing sensitive or regulated material. Upload only documents you are authorized to process.

Develop and test

The runtime has no third-party Python dependencies:

python3 -m unittest discover -s tests -v

Validate the manifest and a development installation with Spec Kit v0.14.3:

specify extension add --dev /absolute/path/to/spec-kit-pdf-context
specify extension list

The test suite uses an in-process mock. It makes no external request and uses no real credential.

Commercial evidence gate

Repository publication, catalog submission, installation, conversion receipts, stars, traffic, owner tests, and free credits are not revenue. After catalog availability, stop or change the route if 60 days and 20 attributed external jobs produce no independent buyer-linked payment received, settled, and reconciled.

License

MIT © 2026 BRAINIALL.