Qooling

Build a self-hosted single-organisation QHSE register. This is a learning and internal-tracking tool, not a certification system, and it should say so on the dashboard.

Stack, no substitutions:
- Next.js (App Router) with TypeScript and Tailwind
- SQLite via Prisma, file at ./data/qhse.db
- Local disk storage for attachments under ./data/uploads
- Single shared password from AUTH_PASSWORD in .env, cookie session, no user accounts, no OAuth, no cloud services, no telemetry

Data model:
- Person: name, email, site
- Incident: type (incident, near miss, unsafe situation), date, site, reporter, description, severity 1-5, photos, status (open, investigating, closed)
- Risk: hazard, activity, likelihood 1-5, impact 1-5, computed score, existing controls, owner, review date
- Action: title, source (incident or risk or audit), owner, due date, status, closure note, closed date
- Document: title, code, current version number, category, owner, review date, uploaded file per version, status (draft, approved, retired)
- AuditLog: append-only table, every create and update writes actor, timestamp, entity, field-level before and after JSON. Never allow deletes on this table in application code.

Screens:
- Dashboard: open incidents, overdue actions, risks above score 15, documents past review date
- List and detail views for each entity, with inline forms, no modals-only flows
- Risk matrix view: 5x5 grid, colour by score, click a cell to see the risks in it
- Evidence pack: pick a date range, get a single printable HTML page with all incidents, actions, risks and document versions in it, plus the relevant audit log rows

In scope: seed script with two sites, five people, sample incidents and risks. CSV export for every list. Overdue highlighting.
Out of scope: mobile app, offline capture, email notifications, e-signatures, multi-tenant, ISO clause libraries, permissions and roles.

On the dashboard, print a fixed banner: "Internal tracking only. Not an audited compliance system."
Include README with setup, .env.example with AUTH_PASSWORD, and a backup script that copies ./data to a timestamped folder.

# AGENTS.md — Build guide for Qooling

## Project scope
A local single-tenant QHSE register: log incidents and risks, attach corrective actions with owners and due dates, keep versioned controlled documents, and export a read-only evidence pack per standard clause.

Catalogue verdict: no. You can absolutely build a register: incidents in, corrective actions out, documents with version numbers, a dashboard that looks convincing. What you cannot build in a session is the thing anyone actually buys, which is an evidence trail an external ISO auditor will accept without argument, plus a mobile flow that a warehouse worker will actually use to report a near miss. Compliance software lives or dies on immutable audit logs, controlled document approval with signatures, retention rules and the fact that the vendor, not you, is the one explaining the system during a certification audit. A personal replacement also makes little sense here: this is inherently multi-user, and the value appears only when an entire site logs into it. Build the register if you want to understand your own processes; do not put your certification on top of it.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- A machine or small VPS to host it
- File storage for document attachments and photos
- Someone willing to define the clause-to-evidence mapping by hand
- Backups you actually test, since this data is the audit

## Stack and architecture
- SQLite via Prisma, file at ./data/qhse.db.
- Data model:.
- Interface for this QHSE and ISO compliance management workflow: a focused QHSE and ISO compliance management input, review, and export interface.

## Security and data integrity
- Out of scope: mobile app, offline capture, email notifications, e-signatures, multi-tenant, ISO clause libraries, permissions and roles.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: Auditor familiarity: external certification bodies have seen the commercial tools and know what to click.

## Agent implementation rules
- Project rule, data: Data model:.
- Project rule, behavior: Incident: type (incident, near miss, unsafe situation), date, site, reporter, description, severity 1-5, photos, status (open, investigating, closed).
- Project rule, recovery: Out of scope: mobile app, offline capture, email notifications, e-signatures, multi-tenant, ISO clause libraries, permissions and roles.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this QHSE and ISO compliance management operation with sample or user-owned data: Incident: type (incident, near miss, unsafe situation), date, site, reporter, description, severity 1-5, photos, status (open, investigating, closed).
- Show a concrete result or export: In scope: seed script with two sites, five people, sample incidents and risks. CSV export for every list. Overdue highlighting.
- State the practical limit: Auditor familiarity: external certification bodies have seen the commercial tools and know what to click.

## Engineering roadmap
1. Phase 1, architecture and data: SQLite via Prisma, file at ./data/qhse.db. Data model:.
2. Phase 2, implement: Incident: type (incident, near miss, unsafe situation), date, site, reporter, description, severity 1-5, photos, status (open, investigating, closed).
3. Phase 3, implement: Risk: hazard, activity, likelihood 1-5, impact 1-5, computed score, existing controls, owner, review date.
4. Phase 4, review and output: Action: title, source (incident or risk or audit), owner, due date, status, closure note, closed date. In scope: seed script with two sites, five people, sample incidents and risks. CSV export for every list. Overdue highlighting.
5. Phase 5, recovery and acceptance: Out of scope: mobile app, offline capture, email notifications, e-signatures, multi-tenant, ISO clause libraries, permissions and roles. Verify this invariant with a saved fixture: A failed or blocked source must be labelled unknown; rerunning the scan must not duplicate the same finding ID. State the practical limit: Auditor familiarity: external certification bodies have seen the commercial tools and know what to click.

## Paid-product capabilities outside this build
- Auditor familiarity: external certification bodies have seen the commercial tools and know what to click
- Immutable, tamper-evident audit logging and controlled document sign-off, which is the whole point of the category
- A field-usable mobile app for incident and near-miss reporting with photos, offline
- Prebuilt ISO 9001 / 14001 / 45001 / 27001 templates, risk matrices and clause mappings you would otherwise write from scratch
- Someone else being accountable when the system fails during an audit or a serious incident investigation

## Implementation prompt
Build a self-hosted single-organisation QHSE register. This is a learning and internal-tracking tool, not a certification system, and it should say so on the dashboard.

Stack, no substitutions:
- Next.js (App Router) with TypeScript and Tailwind
- SQLite via Prisma, file at ./data/qhse.db
- Local disk storage for attachments under ./data/uploads
- Single shared password from AUTH_PASSWORD in .env, cookie session, no user accounts, no OAuth, no cloud services, no telemetry

Data model:
- Person: name, email, site
- Incident: type (incident, near miss, unsafe situation), date, site, reporter, description, severity 1-5, photos, status (open, investigating, closed)
- Risk: hazard, activity, likelihood 1-5, impact 1-5, computed score, existing controls, owner, review date
- Action: title, source (incident or risk or audit), owner, due date, status, closure note, closed date
- Document: title, code, current version number, category, owner, review date, uploaded file per version, status (draft, approved, retired)
- AuditLog: append-only table, every create and update writes actor, timestamp, entity, field-level before and after JSON. Never allow deletes on this table in application code.

Screens:
- Dashboard: open incidents, overdue actions, risks above score 15, documents past review date
- List and detail views for each entity, with inline forms, no modals-only flows
- Risk matrix view: 5x5 grid, colour by score, click a cell to see the risks in it
- Evidence pack: pick a date range, get a single printable HTML page with all incidents, actions, risks and document versions in it, plus the relevant audit log rows

In scope: seed script with two sites, five people, sample incidents and risks. CSV export for every list. Overdue highlighting.
Out of scope: mobile app, offline capture, email notifications, e-signatures, multi-tenant, ISO clause libraries, permissions and roles.

On the dashboard, print a fixed banner: "Internal tracking only. Not an audited compliance system."
Include README with setup, .env.example with AUTH_PASSWORD, and a backup script that copies ./data to a timestamped folder.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.