Osome

Honest answer: don't. Osome is not only an accounting dashboard. Its value
includes human-reviewed books, company administration, tax work, and filings under
local rules. A one-shot clone can organise financial records, but it cannot safely
incorporate a company, act as its secretary, verify its accounts, or take responsibility
for compliance.

If what you need is a personal financial-admin hub before handing records to your
accountant, build this safe slice:

- A local web app: Node + Express + better-sqlite3, server-rendered pages on
  localhost:4780.
- Create customers and sequential invoices with line items, tax rate, due date, and paid
  status; render PDFs with Playwright.
- Record bills and receipts with date, supplier, amount, tax, category, and a file
  attachment stored under ./data/documents/.
- Import bank CSV files and apply editable description-to-category rules; keep unmatched
  transactions in a review queue.
- Show cash received, cash spent, outstanding invoices, and expense totals by month;
  export every table as CSV for my accountant.
- Add a manually maintained compliance calendar. Every deadline records its source URL
  and last-checked date, and the UI labels it unverified until a professional confirms it.
- Provide a document vault grouped by financial year and an export command that creates
  one ZIP containing documents, invoices, and CSV reports.
- Back up the SQLite database and document folder nightly to ./backups/YYYY-MM-DD/,
  keeping 30 copies. No accounts, no telemetry, and no hosted service.
- Out of scope: bank API feeds, payroll, incorporation, corporate-secretary work, tax
  calculations, advice, and government filing. Do not imply that the generated reports
  are statutory accounts.
- Include a README with setup, CSV column mapping, backup recovery, and a warning to have
  all deadlines, books, and filings checked by qualified local professionals.

# AGENTS.md — Build guide for Osome

## Project scope
Build a local financial-admin hub for invoices, receipts, CSV bank imports, rule-based categorisation, cash reports, compliance reminders, and accountant-ready exports, while leaving filings and professional advice to qualified experts.

Catalogue verdict: no. The DIY bookkeeping interface is buildable, but full Osome combines it with human-reviewed books, tax and registry filings, corporate secretarial work, jurisdiction-specific advice, and responsibility for keeping a company compliant. Those services cannot be replaced safely by a one-shot app.
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
- accounting model
- bank CSV imports
- secure document storage
- reliable backups
- accountant and tax review
- local company secretary and compliance expertise

## Stack and architecture
- A local web app: Node + Express + better-sqlite3, server-rendered pages on localhost:4780.
- Model accounts, source transactions, ledger entries, reconciliations, and reports; keep stable source IDs and timestamps.
- Interface for this company incorporation + accounting + compliance workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- On invalid input or interrupted processing, keep the original record, show the failed step, and permit a safe retry.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: company incorporation, government registry filings, and corporate changes.

## Agent implementation rules
- Project rule, data: Model accounts, source transactions, ledger entries, reconciliations, and reports; keep stable source IDs and timestamps.
- Project rule, behavior: Honest answer: don't. Osome is not only an accounting dashboard. Its value.
- Project rule, recovery: On invalid input or interrupted processing, keep the original record, show the failed step, and permit a safe retry.

## 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 company incorporation + accounting + compliance operation with sample or user-owned data: Honest answer: don't. Osome is not only an accounting dashboard. Its value.
- Show a concrete result or export: Show cash received, cash spent, outstanding invoices, and expense totals by month; export every table as CSV for my accountant.
- State the practical limit: company incorporation, government registry filings, and corporate changes.

## Engineering roadmap
1. Phase 1, architecture and data: A local web app: Node + Express + better-sqlite3, server-rendered pages on localhost:4780. Model accounts, source transactions, ledger entries, reconciliations, and reports; keep stable source IDs and timestamps.
2. Phase 2, implement: Honest answer: don't. Osome is not only an accounting dashboard. Its value.
3. Phase 3, implement: Create customers and sequential invoices with line items, tax rate, due date, and paid status; render PDFs with Playwright.
4. Phase 4, review and output: Record bills and receipts with date, supplier, amount, tax, category, and a file attachment stored under ./data/documents/. Show cash received, cash spent, outstanding invoices, and expense totals by month; export every table as CSV for my accountant.
5. Phase 5, recovery and acceptance: On invalid input or interrupted processing, keep the original record, show the failed step, and permit a safe retry. Verify this invariant with a saved fixture: The sum of debits and credits must balance for posted entries; an import retry cannot change the closing balance. State the practical limit: company incorporation, government registry filings, and corporate changes.

## Paid-product capabilities outside this build
- company incorporation, government registry filings, and corporate changes
- qualified bookkeeping review, tax preparation, and statutory filings
- corporate secretary, annual returns, registered address, and nominee services
- live bank and ecommerce feeds with verified reconciliation
- jurisdiction-specific advice, deadline ownership, and human support

## Implementation prompt
Honest answer: don't. Osome is not only an accounting dashboard. Its value
includes human-reviewed books, company administration, tax work, and filings under
local rules. A one-shot clone can organise financial records, but it cannot safely
incorporate a company, act as its secretary, verify its accounts, or take responsibility
for compliance.

If what you need is a personal financial-admin hub before handing records to your
accountant, build this safe slice:

- A local web app: Node + Express + better-sqlite3, server-rendered pages on
  localhost:4780.
- Create customers and sequential invoices with line items, tax rate, due date, and paid
  status; render PDFs with Playwright.
- Record bills and receipts with date, supplier, amount, tax, category, and a file
  attachment stored under ./data/documents/.
- Import bank CSV files and apply editable description-to-category rules; keep unmatched
  transactions in a review queue.
- Show cash received, cash spent, outstanding invoices, and expense totals by month;
  export every table as CSV for my accountant.
- Add a manually maintained compliance calendar. Every deadline records its source URL
  and last-checked date, and the UI labels it unverified until a professional confirms it.
- Provide a document vault grouped by financial year and an export command that creates
  one ZIP containing documents, invoices, and CSV reports.
- Back up the SQLite database and document folder nightly to ./backups/YYYY-MM-DD/,
  keeping 30 copies. No accounts, no telemetry, and no hosted service.
- Out of scope: bank API feeds, payroll, incorporation, corporate-secretary work, tax
  calculations, advice, and government filing. Do not imply that the generated reports
  are statutory accounts.
- Include a README with setup, CSV column mapping, backup recovery, and a warning to have
  all deadlines, books, and filings checked by qualified local professionals.

## 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.