AkurAI-Build

public

Latest change 5ecb45c5915e3bb122d43dbaf90b4eba39484c7d - organize native templates and reserve runtime routes by Olafur Bui

# Bunfork contributor guidance

## Product boundary

- Bunfork is a Linux-first Rust runtime for native MiniJinja pages and **prebuilt, verified static browser artifacts**.
- Do not claim or add source/build/adapter/server-runtime compatibility with Bun, Node, Deno, V8, JavaScriptCore, RSC, Nitro, SvelteKit adapter-node, Next standalone, Vite SSR, or Nuxt/Nitro. Browser JavaScript belongs in admitted static artifacts and is served byte-for-byte.
- Preserve the distinction between native and static modes: static serving must not open the database or load secrets.
- Keep native frontend organization small: `app/pages` owns routes, `app/templates/layouts` owns inheritance, `app/templates/partials` owns included fragments, and `public` owns browser assets. Do not create separate frontend/backend trees for these concerns.
- Native pages must not claim `/api`, `/assets`, or `/_bunfork`; add a regression test when changing route matching.

## Security and data invariants

- Treat artifact admission, manifests, path validation, hashing, preload-before-bind, route canonicalization, cache policy, and HTTP method handling as security-sensitive behavior. Fail closed; do not weaken limits or accept unknown manifest fields without tests and documentation.
- Keep SQLCipher migrations embedded, ordered, transactional, and schema-validated. Never alter a production database directly or make destructive migration shortcuts.
- Secrets stay in protected files or environment variables—never source, fixtures, documentation, logs, or command-line arguments. Maintain constant-time secret comparison.
- Preserve bounded request bodies, concurrency, vector dimensions/results/work, and artifact file/count/size limits. New externally controllable work needs a documented bound and a regression test.

## Implementation and verification

- Keep dependencies minimal and Rust code compatible with the repository lints; do not introduce `unsafe`, `unwrap`, debug macros, TODOs, or unimplemented paths.
- Prefer focused changes. When other agents have uncommitted work, do not reformat, overwrite, or "fix" their files; coordinate and report blockers instead.
- Run `cargo fmt --check` and the relevant tests. Before a release, run `cargo test --locked --all-targets --no-fail-fast`; do not deploy a failing tree.
- Use `bunfork admit` and `bunfork doctor` for static artifacts. Deploy only via `bunfork deploy`; do not manually mutate a digest-owned release directory or bypass its ownership checks.

## Documentation discipline

- Every code change must include the relevant documentation update in the same change.
- Update the closest source of truth: `README.md` for user-facing contracts and commands, `docs/framework-e2e.md` for framework-artifact behavior, and `docs/adversarial/` for security-boundary evidence.
- Keep documentation purposeful and concise: explain changed contracts, limits, or operations; do not restate implementation details or create redundant documents.

## Bunfork-native application contract

The compiled-in Rust application API lives in `src/app.rs` and is exported as
`bunfork::app`. Keep it explicit and static: ordinary route tables, typed
request context, loaders/actions, CSRF helpers, and optional `Store` only.
Never add dynamic plugin loading, runtime JavaScript, framework adapter
compatibility, or application data in cookies. Any change to this contract
must update `README.md`, `docs/adversarial/07-fullstack-contract.md`, and a
focused unit/integration test.

## Browser automation and screenshots (mandatory)

- When Pi needs browser interaction, page inspection, web UI automation, web research requiring page interaction, or a browser screenshot, use the native `agent_browser` tool provided by `pi-agent-browser-native`.
- Do not invoke the `agent-browser` CLI through Bash or substitute ad-hoc browser-driving scripts, Playwright, Puppeteer, or browser DevTools for interactive browser work, unless you are explicitly implementing/testing browser code or the user explicitly requests another workflow.
- Follow the native workflow: `open` → `snapshot -i` → interact with current refs or stable locators → take a fresh `snapshot -i` after navigation or DOM changes. Save requested artifacts to the exact path and verify them before reporting success.
- Device-specific captures such as `tvctl screenshot` remain appropriate when the task is a device diagnostic rather than browser automation; use the native tool for any browser inspection or screenshot around that workflow.

## Autonomous goal mode (mandatory for persistent tasks)

- Use pi-goal's `/goal <objective>` for multi-step implementation, debugging, refactoring, verification, or other work that should continue until it is actually complete. Use `/goal --tokens <budget> <objective>` when a bounded budget is appropriate.
- While a goal is active, continue through implementation and verification rather than stopping at a plan or partial progress. Completion requires the native `goal_complete({ goal_id, summary })` tool with concrete evidence for every requirement.
- Use `goal_blocked({ goal_id, reason, evidence, repeated_turns })` only for a genuine external or terminal blocker that has recurred for at least three consecutive goal turns; difficulty, uncertainty, normal clarification, or a recoverable tool failure is not enough.
- Use `/goal pause`, `/goal resume`, `/goal edit`, and `/goal clear` for goal lifecycle control. Do not create a competing global or directory-based goal state.

## pi-lens

- `pi-lens` is installed globally in Pi via `npm:pi-lens`; restart Pi after installation or upgrades so its extension and skills load.
- Use its LSP diagnostics/navigation, linters, formatters, type-checkers, and structural analysis as feedback while editing code. Fix relevant diagnostics before moving on, while still running the project's normal tests and checks.
- For code discovery, prefer the `symbol_search` → `module_report` → `read_symbol` funnel; use AST search/replace for structural changes when appropriate.
- Treat pi-lens diagnostics as advisory project feedback: do not hide, suppress, or bypass a finding without understanding and documenting the reason.