docs / ai / using-the-ai.md

Using the AI Effectively

The chat is the primary way you work with entrytwo. You give instructions in natural language, attach documents, and the AI either creates real journal entries (autonomously at high confidence) or returns clear proposals for you to confirm.

This guide focuses on practical usage.

Basic Interaction

Type in the chat box on the left.
Attach files (PDF statements, receipts, images, CSVs) using the paperclip icon.
Send. The AI reads the current view (branch + as-of), the ledger snapshot, recent rates, and any attached files.
It responds with text, and often an action (create entries, create contact, propose something, open a ledger, etc.).

After an autonomous creation you will often see a small "View in list" link to jump to the result (journal, contacts, claims, etc.).

Attaching Documents - "Staged Receipts"

You can attach files before or during a conversation.

Attached files become part of a persistent "staged" list until used.
You can discuss a document over several messages.
When an entry is created (AI or manual), the staged receipt is usually consumed and linked to that journal entry.
This is useful for: "Here is the Visa statement... now create the entries... also split the big one into office supplies and software."

You can also upload via the top bar → Receipts panel, then attach from there later.

Supported: PDF, images (jpg/png/webp), CSV for import.

Chat Lock (Critical Safety Control)

Near the chat input there is a lock/unlock icon:

Unlocked: AI may autonomously execute safe actions when confidence is high and everything validates.
Locked: AI only returns proposals. Nothing changes the books until you explicitly confirm.

Toggle it anytime. A banner appears when locked: "Chat locked - proposals only."

Recommendation:

Start unlocked while you are testing with real data.
Lock it when you are in sensitive periods, closing the books, or just prefer full control.

The lock is enforced server-side - it is not just a UI hint.

See docs/ai/ai-autonomy.md for the exact rules.

Good Prompting Patterns

Be specific and use the language of accounting + the Git model.

Statement / receipt processing

Upload the PDF first, then:

Process this Visa statement for June. Create one journal entry per transaction.
Use the rates shown on the statement where available.

Extract the transactions from this bank statement and create the entries.

Reconciliation

Reconcile the 1100 account for last month and explain anything that didn't match.

Run reconciliation on 2100 (credit cards) from 2026-06-01 to 2026-06-30.

Explain / investigate

Why is the cash account not zero?

Show me all unreconciled items on 1000 this quarter.

Corrections and adjustments

On the june-recon branch, create the adjusting entry for the timing difference we discussed.

Reverse the entry from last week that duplicated the rent payment.

Creating other things

Create a contact "Acme Corp" as CUSTOMER with email billing@acme.example.

Create an expense claim draft for my train ticket to Berlin on 2026-07-10, 89.50 EUR on 5200.

Working with views (branch / as-of)

The AI always works on the current view shown in the top indicator.

If you are on a branch or historical point, just say what you want:

Tag this view as "june-close-2026".

Restore the books to 2026-06-15 14:30 on main.

What Happens After You Send a Message

The model proposes an action (or just answers).
Server validates (balanced, accounts exist, FX rules, etc.).
If safe + high confidence + chat unlocked → executes and creates a real commit (AI_AUTONOMOUS_ENTRY).
Otherwise → returns a proposal for you to review/confirm.

For journal entries that need review, the New Journal Entry modal usually opens pre-filled.

For other proposals you get confirm/cancel buttons.

Reviewing and Fixing AI Work

Use the Audit Log (view=audit or Admin) to see exactly what was created and by whom (or which AI model).
Use History (?view=history) for branches, recent states, blame, diff, restore.
If something is wrong:
Reverse the entry (creates a reversing entry, never mutates the original).
Or restore to a known good point (always creates a new ROLLBACK commit).
You can ask the AI to explain any entry or discrepancy.

Nothing the AI does is "magic" or hidden. Everything is a normal audited commit.

FX and Foreign Currency Rules (Important)

The AI is very strict about exchange rates:

New foreign amounts usually start as provisional (LLM_PROVISIONAL + source URLs from web search).
Only rates that actually came from a bank statement/feed in this turn may be marked BANK_FEED.
It must balance in base currency.
If it cannot find a reliable rate, it will usually refuse to create the entry and explain why.

When a later statement arrives with the real rate, ask for an adjustment entry only (do not touch the original).

Common Workflows

Bank/credit card statement → entries

Attach PDF or paste table.
"Process this statement."
Review any proposals.
Confirm or let high-confidence ones go through autonomously.
Check the ledger or reconciliation view.

Receipt → expense or journal

Attach photo or PDF of receipt.
"Create a journal entry for this office supplies receipt, 47.20 EUR incl. 19% VAT."
Or: "Create an expense claim draft for this."

Month-end close

Switch to or create a working branch if desired.
Reconcile key accounts via chat or Git controls.
Ask for explanations of any differences.
Create adjusting entries.
Tag the view (e.g. "june-close").
When happy, merge or restore as needed.

"What if" or correction work

Create a branch from the current view.
Do the experimental work there.
Use diff/merge when ready, or just abandon the branch.

Tips for Better Results

Upload clear, complete documents (full statements > single transactions).
Use account codes that actually exist (the AI is given the current chart).
Be explicit about dates and periods when they matter.
Mention the current view only if you are not on main/current.
For risky work, say "propose only" or work on a branch.
Stage multiple related receipts before asking for entries if you want them all attached.
After autonomous work, quickly scan the recent entries or use blame to verify.

What the AI Will Not Do Autonomously

Create or change accounts (chart of accounts).
Change tax rates or company settings.
Manage users.
Send invoices or trigger payments (always proposals).
Perform restores or merges without preview + confirmation.
Anything destructive or master-data.

These will always come back as proposals (or be rejected with a message).

When to Use Chat vs UI Controls

Use chat for:

Creating entries from documents
Reconciliation and explanations
Quick contact or draft creation
Natural-language investigation

Use the dedicated UI panels / Git controls for:

Browsing history, branches, tags
Manual restore with preview
Blame and diff on specific accounts
Detailed review of claims or invoices

They are complementary. The Git model (branch + asOf) is respected everywhere.