clean up documentation for npm users

Author: wassertim

README.md

@@ -1,8 +1,10 @@
 # abacus-cli
 
-CLI tool for automating time entry logging in [Abacus ERP](https://www.abacus.ch) via Playwright browser automation.
+CLI tool for logging time entries in [Abacus ERP](https://www.abacus.ch) from the terminal.
 
-[Abacus](https://www.abacus.ch) is a Swiss ERP system widely used by companies in Switzerland for accounting, payroll, and time tracking. Its web portal is built on Vaadin (a server-side Java UI framework) and does not expose a REST API — so this tool uses headless browser automation instead. The CLI drives a real Chromium browser, fills forms, reads grids, and handles Vaadin's async server round-trips.
+[Abacus](https://www.abacus.ch) is a Swiss ERP system widely used for accounting, payroll, and time tracking. Its web portal does not expose a REST API, so this tool uses Playwright to drive a headless Chromium browser — filling forms, reading grids, and handling the UI automatically.
+
+**[Documentation](https://wassertim.github.io/abacus-cli/en/)**
 
 ## Who is this for?
 
@@ -13,33 +15,32 @@ This project is open source under the MIT license. You're welcome to fork it, ad
 ## Prerequisites
 
 - Node.js 18+
-- A running Abacus instance you have credentials for
+- Access to an Abacus web portal (provided by your company)
 
 ## Setup
 
+```bash
+npm install -g abacus-cli
+```
+
+Chromium is downloaded automatically on install for browser automation.
+
+### From source
+
 ```bash
 git clone https://github.com/wassertim/abacus-cli.git
 cd abacus-cli
 npm install
 npm run build
-npm link          # makes `abacus` available globally
+npm link
 ```
 
-### Configuration
-
-Set your Abacus instance URL via environment variable:
+### Configure your Abacus URL
 
 ```bash
-export ABACUS_URL="https://your-abacus-instance.example.com/portal/myabacus"
+abacus config set url https://your-abacus-instance.example.com/portal/myabacus
 ```
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `ABACUS_URL` | `https://abacus.example.com/portal/myabacus` | Base URL of your Abacus portal |
-| `ABACUS_CONFIG_DIR` | `~/.abacus-cli` | Directory for session state and discovery data |
-
-## Usage
-
 ### Login
 
 Opens a real browser window for manual login. Session cookies are persisted locally so subsequent commands run headlessly.
@@ -48,17 +49,19 @@ Opens a real browser window for manual login. Session cookies are persisted loca
 abacus login
 ```
 
+## Usage
+
 ### Log time
 
 ```bash
-abacus time log --project 71100000001 --hours 8 --service-type 1435 --text "Development" --date 2025-01-15
+abacus time log --project 12345 --hours 8 --service-type 100 --text "Development" --date 2025-01-15
 ```
 
 | Flag | Required | Default | Description |
 |------|----------|---------|-------------|
 | `--project <id>` | no | — | Project number or alias (interactive prompt if omitted) |
 | `--hours <n>` | yes | — | Hours to log |
-| `--service-type <id>` | no | `1435` | Service type ID or alias |
+| `--service-type <id>` | no | `100` | Service type ID or alias |
 | `--text <text>` | yes | — | Description |
 | `--date <YYYY-MM-DD>` | no | today | Entry date |
 
@@ -87,13 +90,13 @@ Create multiple time entries in a single browser session — much faster than ru
 
 ```bash
 # Fill current week (Mon-Fri)
-abacus time batch --project 71100000001 --hours 8 --service-type 1435 --text "Development"
+abacus time batch --project 12345 --hours 8 --service-type 100 --text "Development"
 
 # Fill specific date range
-abacus time batch --from 2026-01-26 --to 2026-01-30 --project 71100000001 --hours 8 --text "Dev"
+abacus time batch --from 2026-01-26 --to 2026-01-30 --project 12345 --hours 8 --text "Dev"
 
 # Preview what would be created
-abacus time batch --project 71100000001 --hours 8 --text "Dev" --dry-run
+abacus time batch --project 12345 --hours 8 --text "Dev" --dry-run
 ```
 
 **Generate template** — finds missing days and writes a pre-filled file:
@@ -116,21 +119,21 @@ abacus time batch --file entries.json --include-weekends
 JSON format:
 ```json
 [
-  { "date": "2026-02-02", "project": "71100000001", "serviceType": "1435", "hours": 8, "text": "Development" }
+  { "date": "2026-02-02", "project": "12345", "serviceType": "100", "hours": 8, "text": "Development" }
 ]
 ```
 
 CSV format:
 ```
 date,project,serviceType,hours,text
-2026-02-02,71100000001,1435,8,Development
+2026-02-02,12345,100,8,Development
 ```
 
 | Flag | Description |
 |------|-------------|
 | `--project <id>` | Project number or alias (required for range fill) |
 | `--hours <n>` | Hours per entry (required for range fill) |
-| `--service-type <id>` | Service type (default: 1435) |
+| `--service-type <id>` | Service type (default: 100) |
 | `--text <text>` | Description |
 | `--from <YYYY-MM-DD>` | Start date (default: Monday of current week) |
 | `--to <YYYY-MM-DD>` | End date (default: Friday of current week) |
@@ -155,7 +158,7 @@ This opens a checkbox picker with all entries for the current month. Navigate wi
 **Targeted mode** — delete a specific entry by date and project:
 
 ```bash
-abacus time delete --date 2025-01-15 --project 71100000001
+abacus time delete --date 2025-01-15 --project 12345
 ```
 
 | Flag | Required | Description |
@@ -201,8 +204,8 @@ Create short names for frequently used project numbers and service types.
 
 ```bash
 abacus alias list
-abacus alias add project myproj 71100000001
-abacus alias add service-type dev 1435
+abacus alias add project myproj 12345
+abacus alias add service-type dev 100
 abacus alias remove project myproj
 ```
 
@@ -220,6 +223,13 @@ abacus config set url https://your-instance.example.com/portal/myabacus
 abacus config set locale de                 # Override locale (de, en, fr, it, es)
 ```
 
+Environment variables can also be used:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ABACUS_URL` | — | Base URL of your Abacus portal |
+| `ABACUS_CONFIG_DIR` | `~/.abacus-cli` | Directory for session state |
+
 ### Session refresh
 
 Keep your saved session alive by refreshing it periodically. On macOS, you can install a launchd agent to do this automatically.
@@ -241,11 +251,13 @@ abacus discover
 
 ## How it works
 
+Abacus's web portal is built on [Vaadin](https://vaadin.com/), a server-side Java UI framework. There is no REST API — every interaction happens through the browser DOM with server round-trips for each action.
+
 1. **Login** — Opens a headed browser for manual SSO/login. Saves cookies and localStorage to `~/.abacus-cli/state.json`.
-2. **Automation** — Restores the saved session in a headless browser. Navigates to the Leistungen (time entries) page via Vaadin's menu system.
+2. **Automation** — Restores the saved session in a headless browser and navigates through Vaadin's menu system to the time entries page.
 3. **Vaadin handling** — Comboboxes require character-by-character input with delays to trigger server-side filtering. `waitForVaadin()` polls the client to ensure no pending server requests before proceeding.
 4. **Duplicate detection** — Before creating an entry, existing entries for the same date and project are checked. You can choose to update or create new.
-5. **Captcha fallback** — If a FortiADC captcha is detected, the browser reopens in headed mode for manual solving, then retries automatically.
+5. **Captcha fallback** — If a captcha is detected, the browser reopens in headed mode for manual solving, then retries automatically.
 
 ## Development
 

site/public/og-image.png

@@ -32,10 +32,10 @@ export default {
     },
     howItWorks: {
       title: 'So funktioniert es',
-      step1: 'Login — Öffnet einen echten Browser für manuelles SSO/Login. Die Session wird lokal gespeichert.',
-      step2: 'Automatisierung — Stellt die Session headless wieder her und navigiert durch Vaadins UI.',
-      step3: 'Smarte Eingabe — Zeichen-für-Zeichen Combobox-Eingabe, Server-Roundtrip-Polling, Duplikaterkennung.',
-      step4: 'Captcha-Fallback — Falls ein Captcha erscheint, öffnet sich der Browser zur manuellen Lösung und versucht es dann erneut.',
+      step1: 'Einmal im echten Browser einloggen. Ihre Session wird lokal gespeichert.',
+      step2: 'Beliebigen Befehl ausführen — ein unsichtbarer Browser öffnet sich, stellt Ihre Session wieder her und erledigt die Arbeit.',
+      step3: 'Bestehende Einträge werden automatisch erkannt, damit keine Duplikate entstehen.',
+      step4: 'Falls Ihr Unternehmen ein Captcha nutzt, öffnet sich der Browser zur manuellen Lösung und fährt dann fort.',
     },
   },
   gettingStarted: {

site/public/og-image.svg

@@ -32,10 +32,10 @@ export default {
     },
     howItWorks: {
       title: 'How it works',
-      step1: 'Login — Opens a real browser for manual SSO/login. Session is saved locally.',
-      step2: 'Automation — Restores the session headlessly and navigates Vaadin\'s UI.',
-      step3: 'Smart handling — Character-by-character combobox input, server round-trip polling, duplicate detection.',
-      step4: 'Captcha fallback — If a captcha appears, the browser reopens for manual solving, then retries.',
+      step1: 'Log in once in a real browser window. Your session is saved locally.',
+      step2: 'Run any command — it opens a headless browser, restores your session, and does the work.',
+      step3: 'Existing entries are detected automatically so you don\'t create duplicates.',
+      step4: 'If your company uses a captcha, the browser reopens so you can solve it, then continues.',
     },
   },
   gettingStarted: {

site/src/i18n/de.ts

@@ -31,17 +31,19 @@ const alternateUrl = `https://wassertim.github.io${localePath(other, pagePath)}`
     <link rel="canonical" href={canonicalUrl} />
     <link rel="alternate" hreflang={locale} href={canonicalUrl} />
     <link rel="alternate" hreflang={other} href={alternateUrl} />
+    <link rel="alternate" hreflang="x-default" href={canonicalUrl} />
 
+    <meta property="og:locale" content={locale === 'de' ? 'de_DE' : 'en_US'} />
     <meta property="og:type" content="website" />
     <meta property="og:title" content={title} />
     <meta property="og:description" content={description} />
     <meta property="og:url" content={canonicalUrl} />
-    <meta property="og:image" content="https://wassertim.github.io/abacus-cli/og-image.svg" />
+    <meta property="og:image" content="https://wassertim.github.io/abacus-cli/og-image.png" />
 
     <meta name="twitter:card" content="summary_large_image" />
     <meta name="twitter:title" content={title} />
     <meta name="twitter:description" content={description} />
-    <meta name="twitter:image" content="https://wassertim.github.io/abacus-cli/og-image.svg" />
+    <meta name="twitter:image" content="https://wassertim.github.io/abacus-cli/og-image.png" />
 
     <link rel="icon" type="image/svg+xml" href="/abacus-cli/favicon.svg" />
   </head>

site/src/i18n/en.ts

@@ -22,7 +22,7 @@ const t = getTranslations(locale);
     <thead><tr><th>Variable</th><th>Standard</th><th>Beschreibung</th></tr></thead>
     <tbody>
       <tr><td><code>ABACUS_URL</code></td><td><code>https://abacus.example.com/portal/myabacus</code></td><td>Basis-URL Ihres Abacus-Portals</td></tr>
-      <tr><td><code>ABACUS_CONFIG_DIR</code></td><td><code>~/.abacus-cli</code></td><td>Verzeichnis für Session-Daten und Discovery-Dateien</td></tr>
+      <tr><td><code>ABACUS_CONFIG_DIR</code></td><td><code>~/.abacus-cli</code></td><td>Verzeichnis für Session-Daten</td></tr>
       <tr><td><code>ABACUS_LOCALE</code></td><td>automatisch erkannt</td><td>UI-Sprache überschreiben (de, en, fr, it, es)</td></tr>
     </tbody>
   </table>
@@ -39,8 +39,8 @@ abacus config set locale de                 # Sprache überschreiben (de, en, fr
   <p>Kurznamen für häufig verwendete Projektnummern und Leistungsarten erstellen.</p>
   <CodeBlock>
     <pre><code>abacus alias list
-abacus alias add project meinprojekt 71100000001
-abacus alias add service-type entw 1435
+abacus alias add project meinprojekt 12345
+abacus alias add service-type entw 100
 abacus alias remove project meinprojekt</code></pre>
   </CodeBlock>
   <p>Einmal definiert, können Aliase überall statt numerischer IDs verwendet werden:</p>

site/src/layouts/Base.astro

@@ -25,14 +25,14 @@ const t = getTranslations(locale);
   <h2 id="time-log">abacus time log</h2>
   <p>Einen einzelnen Zeiteintrag erfassen.</p>
   <CodeBlock>
-    <pre><code>abacus time log --project 71100000001 --hours 8 --service-type 1435 --text "Entwicklung" --date 2025-01-15</code></pre>
+    <pre><code>abacus time log --project 12345 --hours 8 --service-type 100 --text "Entwicklung" --date 2025-01-15</code></pre>
   </CodeBlock>
   <table>
     <thead><tr><th>Flag</th><th>Pflicht</th><th>Standard</th><th>Beschreibung</th></tr></thead>
     <tbody>
       <tr><td><code>--project &lt;id&gt;</code></td><td>nein</td><td>—</td><td>Projektnummer oder Alias (interaktive Auswahl falls weggelassen)</td></tr>
       <tr><td><code>--hours &lt;n&gt;</code></td><td>ja</td><td>—</td><td>Zu erfassende Stunden</td></tr>
-      <tr><td><code>--service-type &lt;id&gt;</code></td><td>nein</td><td><code>1435</code></td><td>Leistungsart-ID oder Alias</td></tr>
+      <tr><td><code>--service-type &lt;id&gt;</code></td><td>nein</td><td><code>100</code></td><td>Leistungsart-ID oder Alias</td></tr>
       <tr><td><code>--text &lt;text&gt;</code></td><td>ja</td><td>—</td><td>Beschreibung</td></tr>
       <tr><td><code>--date &lt;YYYY-MM-DD&gt;</code></td><td>nein</td><td>heute</td><td>Datum des Eintrags</td></tr>
     </tbody>
@@ -58,13 +58,13 @@ abacus time list --monthYear 01.2025  # bestimmter Monat</code></pre>
   <p>Füllt alle Wochentage in einem Zeitraum:</p>
   <CodeBlock>
     <pre><code># Aktuelle Woche füllen (Mo-Fr)
-abacus time batch --project 71100000001 --hours 8 --service-type 1435 --text "Entwicklung"
+abacus time batch --project 12345 --hours 8 --service-type 100 --text "Entwicklung"
 
 # Bestimmten Zeitraum füllen
-abacus time batch --from 2026-01-26 --to 2026-01-30 --project 71100000001 --hours 8 --text "Entw."
+abacus time batch --from 2026-01-26 --to 2026-01-30 --project 12345 --hours 8 --text "Entw."
 
 # Vorschau ohne Erstellung
-abacus time batch --project 71100000001 --hours 8 --text "Entw." --dry-run</code></pre>
+abacus time batch --project 12345 --hours 8 --text "Entw." --dry-run</code></pre>
   </CodeBlock>
 
   <h3>Vorlage generieren</h3>
@@ -89,7 +89,7 @@ abacus time batch --file eintraege.json --include-weekends</code></pre>
     <tbody>
       <tr><td><code>--project &lt;id&gt;</code></td><td>Projektnummer oder Alias (Pflicht bei Bereichsfüllung)</td></tr>
       <tr><td><code>--hours &lt;n&gt;</code></td><td>Stunden pro Eintrag (Pflicht bei Bereichsfüllung)</td></tr>
-      <tr><td><code>--service-type &lt;id&gt;</code></td><td>Leistungsart (Standard: 1435)</td></tr>
+      <tr><td><code>--service-type &lt;id&gt;</code></td><td>Leistungsart (Standard: 100)</td></tr>
       <tr><td><code>--text &lt;text&gt;</code></td><td>Beschreibung</td></tr>
       <tr><td><code>--from &lt;YYYY-MM-DD&gt;</code></td><td>Startdatum (Standard: Montag der aktuellen Woche)</td></tr>
       <tr><td><code>--to &lt;YYYY-MM-DD&gt;</code></td><td>Enddatum (Standard: Freitag der aktuellen Woche)</td></tr>
@@ -110,7 +110,7 @@ abacus time batch --file eintraege.json --include-weekends</code></pre>
 
   <p><strong>Gezielter Modus</strong> — bestimmten Eintrag nach Datum und Projekt löschen:</p>
   <CodeBlock>
-    <pre><code>abacus time delete --date 2025-01-15 --project 71100000001</code></pre>
+    <pre><code>abacus time delete --date 2025-01-15 --project 12345</code></pre>
   </CodeBlock>
 
   <h2 id="summary">abacus summary</h2>
@@ -132,9 +132,4 @@ Overtime: +12.5h (1.6d) · Vacation: 15.0d left
     <pre><code>abacus check 2>/dev/null</code></pre>
   </CodeBlock>
 
-  <h2 id="discover">abacus discover</h2>
-  <p>Zeichnet Netzwerkanfragen auf, während Sie manuell mit Abacus interagieren. Nützlich zum Verstehen von Vaadins Kommunikationsprotokoll.</p>
-  <CodeBlock>
-    <pre><code>abacus discover</code></pre>
-  </CodeBlock>
 </Docs>

site/src/pages/de/docs/configuration.astro

@@ -19,17 +19,14 @@ const t = getTranslations(locale);
   <h2 id="prerequisites">{t.gettingStarted.prerequisites}</h2>
   <ul>
     <li>Node.js 18+</li>
-    <li>Eine laufende Abacus-Instanz, für die Sie Zugangsdaten haben</li>
+    <li>Zugang zu einem Abacus-Webportal (von Ihrem Unternehmen bereitgestellt)</li>
   </ul>
 
   <h2 id="installation">{t.gettingStarted.installation}</h2>
   <CodeBlock title="Terminal">
-    <pre><code>git clone https://github.com/wassertim/abacus-cli.git
-cd abacus-cli
-npm install
-npm run build
-npm link          # macht `abacus` global verfügbar</code></pre>
+    <pre><code>npm install -g abacus-cli</code></pre>
   </CodeBlock>
+  <p>Chromium wird bei der Installation automatisch heruntergeladen.</p>
 
   <h2 id="configuration">{t.gettingStarted.configuration}</h2>
   <p>Setzen Sie die URL Ihrer Abacus-Instanz als Umgebungsvariable:</p>
@@ -58,7 +55,7 @@ npm link          # macht `abacus` global verfügbar</code></pre>
       <tr>
         <td><code>ABACUS_CONFIG_DIR</code></td>
         <td><code>~/.abacus-cli</code></td>
-        <td>Verzeichnis für Session-Daten und Discovery-Dateien</td>
+        <td>Verzeichnis für Session-Daten</td>
       </tr>
     </tbody>
   </table>
@@ -71,7 +68,7 @@ npm link          # macht `abacus` global verfügbar</code></pre>
 
   <h2 id="first-entry">{t.gettingStarted.firstEntry}</h2>
   <CodeBlock>
-    <pre><code>abacus time log --project 71100000001 --hours 8 --service-type 1435 --text "Entwicklung"</code></pre>
+    <pre><code>abacus time log --project 12345 --hours 8 --service-type 100 --text "Entwicklung"</code></pre>
   </CodeBlock>
   <p>Falls ein passender Eintrag (gleiches Datum + Projekt) bereits existiert, werden Sie gefragt, ob Sie ihn aktualisieren oder einen neuen erstellen möchten.</p>
 

site/src/pages/de/docs/index.astro

@@ -22,7 +22,7 @@ const t = getTranslations(locale);
     <thead><tr><th>Variable</th><th>Default</th><th>Description</th></tr></thead>
     <tbody>
       <tr><td><code>ABACUS_URL</code></td><td><code>https://abacus.example.com/portal/myabacus</code></td><td>Base URL of your Abacus portal</td></tr>
-      <tr><td><code>ABACUS_CONFIG_DIR</code></td><td><code>~/.abacus-cli</code></td><td>Directory for session state and discovery data</td></tr>
+      <tr><td><code>ABACUS_CONFIG_DIR</code></td><td><code>~/.abacus-cli</code></td><td>Directory for session state</td></tr>
       <tr><td><code>ABACUS_LOCALE</code></td><td>auto-detected</td><td>Override the UI locale (de, en, fr, it, es)</td></tr>
     </tbody>
   </table>
@@ -39,8 +39,8 @@ abacus config set locale de                 # Override locale (de, en, fr, it, e
   <p>Create short names for frequently used project numbers and service types.</p>
   <CodeBlock>
     <pre><code>abacus alias list
-abacus alias add project myproj 71100000001
-abacus alias add service-type dev 1435
+abacus alias add project myproj 12345
+abacus alias add service-type dev 100
 abacus alias remove project myproj</code></pre>
   </CodeBlock>
   <p>Once defined, use aliases anywhere instead of numeric IDs:</p>