entrytwo
buy

docs / getting-started / first-steps.md

First Steps

This guide walks you through your first few minutes with a fresh entrytwo installation.

1. First Visit - Bootstrap the Initial Admin

On a brand new instance:

  1. Open the app (usually http://localhost:3000 or your domain).
  2. You are redirected to the sign-in page.
  3. If no admin user exists yet, you see "Create First Admin".
  4. Enter your email, choose the default language (UI + standard chart of accounts), and submit.

In local development this creates the admin session immediately (instant email — no SMTP required).

In production, configure SMTP and/or OAuth first. After bootstrap, sign in with magic link or Google/Microsoft. ADMIN users must then complete TOTP (2FA) setup before using the app.

After this step you are an ADMIN and can access the full application.

Important: The first admin only bootstraps the system. Later users join via invitation (Admin → Users) and must use the exact invited email.

2. Initial Onboarding (Company + Chart of Accounts)

Right after the first admin signs in, the app may show an onboarding / bootstrap panel (visible in Admin or automatically on first load).

You will typically set:

  • Company name
  • Base currency (e.g. EUR, USD)
  • A standard chart of accounts is seeded (1000 Cash, 1010 Bank, 2000 Accounts Payable, 3000 Retained Earnings, 4000 Revenue, 5000 Expenses, plus common tax rates).

You can later customize accounts, tax rates, and settings under Admin.

Once this is done, the main /app interface loads.

3. The Main Screen

Layout:

  • Left: Chat (your primary way of talking to the AI and creating entries).
  • Right / main area: Dynamic panels (dashboard, journal, ledger, accounts, reports, etc.).
  • Top bar: View switcher, settings (gear) menu — admin links, license, Sign out — trial/license status, chat lock near the chat input.

Default view is the dashboard, which shows:

  • A persistent "Books View" indicator (branch + as-of state).
  • Recent journal entries.
  • Summary bar.
  • Other key panels.

You can switch views from the top navigation or by using ?view=... in the URL.

4. Chat Basics

The chat is the heart of entrytwo.

Try these:

  • "Upload a receipt or statement PDF using the paperclip, then say: Create journal entries for this."
  • "Reconcile the 1100 account for last month and explain any differences."
  • "Create a contact named Acme Corp as CUSTOMER."
  • "Why is the cash account not zero?"

Attachments (staged receipts):

  • You can attach PDFs, images, or CSVs to messages.
  • They become part of a "pending receipt state" until used in a journal entry.
  • This lets you discuss a document over several turns and then create the entry.

Chat Lock (lock icon near the input):

  • Unlocked = AI can autonomously execute safe actions when confident.
  • Locked = AI only proposes; you must confirm everything.

Most people start with it unlocked after they have seen it work on a few real documents, then lock it for sensitive periods.

See docs/ai/ai-autonomy.md for details.

5. Your First Real Work

Recommended first flow:

  1. Upload a bank statement or vendor invoice PDF via the paperclip in chat or the Upload button in the top bar.
  2. Ask the AI to process it: "Create the journal entries for this statement."
  3. Review any proposals (if confidence was not high enough or lock is on).
  4. Confirm or edit the journal entry.
  5. Go to Accounts or Ledger to see the effect.
  6. Use the History view (?view=history) to explore branches, recent states, reconcile, or tag a point.

6. Key Concepts to Internalize Early

  • Current view (branch + asOf): Everything you see and do is relative to the branch and point-in-time shown in the indicator. The AI respects this.
  • main is the official protected books.
  • Other branches are safe places to experiment.
  • History is immutable. Restore always creates a new ROLLBACK commit.
  • AI actions at high confidence create real AI_AUTONOMOUS_ENTRY commits (fully auditable).

Read docs/concepts/git-model.md soon - it explains the philosophy that everything else is built on.

7. Common Early Actions

  • Open a specific account ledger: click an account code or use chat ("open the ledger for 1100").
  • Filter the whole dashboard to one account.
  • View full journal: ?view=journal.
  • Go to Git/history controls: ?view=history.
  • Upload more receipts later via Admin or the receipts panel and attach them to entries.
  • Create expense claims (collect receipts, submit, approve, post).

8. Next Steps

  • Configure SMTP (magic link + invitation email) and/or Google / Microsoft OAuth so other users can sign in. Invite them from Admin → Users; they must use the invited address.
  • Sign out anytime from the settings (gear) menu.
  • Add real bank feeds (Admin → Bank Feeds) if you have Stripe or other supported processors.
  • Set up recurring journals or automation.
  • Read about updates and licensing if you are running this for real use.
  • Explore the Admin area (users, periods, tax, AI settings, backup, etc.).

Quick Troubleshooting

  • "No admin exists" keeps showing → Check that the first bootstrap actually succeeded (look in logs or database).
  • Chat does nothing or errors → Make sure an LLM key is configured and the provider/model is reachable.
  • Can't see recent entries → Try the "Refresh all" button or hard refresh.
  • Database connection issues → Verify DATABASE_URL and that Postgres is running and healthy.

For more, see docs/troubleshooting/common-issues.md (to be expanded) and the internal entrytwo_v1/docs/SETUP.md.

You now have a working entrytwo instance. The rest of the documentation will make much more sense once you have done the above steps with real data.