docs: Improve formatting and add WIP notice

- Update .gitignore with env files and logs patterns
- Add work-in-progress warning to README
- Fix code formatting and table alignment in SKILL.md

Author: maelcaldas

.gitignore

@@ -10,3 +10,11 @@ node_modules/
 # OS
 .DS_Store
 Thumbs.db
+
+# Environment files (prevent accidental commits)
+.env
+.env.*
+*.local
+
+# Logs
+*.log

README.md

@@ -1,3 +1,11 @@
+> **⚠️ Work in Progress**
+> 
+> This repository is under active development and is **not ready for external use**.
+> The skills, APIs, and documentation may change significantly without notice.
+> Please do not depend on this repository until it reaches a stable release.
+
+---
+
 # Skills
 
 AI agent skills for Bkper development. These skills provide procedural knowledge to AI coding assistants (Claude Code, OpenCode, Gemini CLI) when working on Bkper projects.

skills/bkper-app-dev/SKILL.md

@@ -13,12 +13,12 @@ Core knowledge for building Bkper apps using `bkper-js` SDK and Workers for Plat
 
 ### Account Types
 
-| Type | Nature | Balance Behavior |
-|------|--------|------------------|
-| `ASSET` | Permanent | Increases with debits |
+| Type        | Nature    | Balance Behavior       |
+| ----------- | --------- | ---------------------- |
+| `ASSET`     | Permanent | Increases with debits  |
 | `LIABILITY` | Permanent | Increases with credits |
-| `INCOMING` | Temporary | Increases with credits |
-| `OUTGOING` | Temporary | Increases with debits |
+| `INCOMING`  | Temporary | Increases with credits |
+| `OUTGOING`  | Temporary | Increases with debits  |
 
 ### The Zero-Sum Invariant
 
@@ -35,15 +35,14 @@ bun add bkper-js
 ### Initialization (Cloudflare Workers)
 
 ```typescript
-import { Bkper, Book } from 'bkper-js';
+import { Bkper, Book } from "bkper-js";
 
 // Per-request Bkper instance (recommended for Workers)
 function createBkper(env: Env, oauthToken?: string): Bkper {
-  return new Bkper({
-    apiKeyProvider: async () => env.BKPER_API_KEY,
-    oauthTokenProvider: async () => oauthToken,
-    agentIdProvider: async () => env.BKPER_AGENT_ID,
-  });
+    return new Bkper({
+        oauthTokenProvider: async () => oauthToken,
+        agentIdProvider: async () => env.BKPER_AGENT_ID,
+    });
 }
 ```
 
@@ -58,12 +57,11 @@ const book = await bkper.getBook(bookId, true);
 
 // Book properties
 book.getName();
-book.getDatePattern();      // dd/MM/yyyy | MM/dd/yyyy | yyyy/MM/dd
-book.getFractionDigits();   // decimal places (0-8)
+book.getDatePattern(); // dd/MM/yyyy | MM/dd/yyyy | yyyy/MM/dd
+book.getFractionDigits(); // decimal places (0-8)
 book.formatDate(new Date());
 book.parseDate("25/01/2024");
 book.formatValue(1234.56);
-book.round(amount);
 
 // Get accounts
 const accounts = await book.getAccounts();
@@ -73,26 +71,26 @@ const account = await book.getAccount("Account Name");
 ### Transaction Operations
 
 ```typescript
-import { Transaction } from 'bkper-js';
+import { Transaction } from "bkper-js";
 
 // Create and post a transaction
 const tx = new Transaction(book)
-  .setDate("2024-01-25")
-  .setAmount(100.50)
-  .from(creditAccount)
-  .to(debitAccount)
-  .setDescription("Payment #invoice123")
-  .setProperty("external_id", "123")
-  .addRemoteId("external-system-id");
+    .setDate("2024-01-25")
+    .setAmount(100.5)
+    .from(creditAccount)
+    .to(debitAccount)
+    .setDescription("Payment #invoice123")
+    .setProperty("external_id", "123")
+    .addRemoteId("external-system-id");
 
-await tx.create();  // Create as draft
-await tx.post();    // Post (affects balances)
+await tx.create(); // Create as draft
+await tx.post(); // Post (affects balances)
 
 // Transaction lifecycle
-await tx.check();    // Mark as reconciled
-await tx.uncheck();  // Unmark
-await tx.trash();    // Move to trash
-await tx.update();   // Update
+await tx.check(); // Mark as reconciled
+await tx.uncheck(); // Unmark
+await tx.trash(); // Move to trash
+await tx.update(); // Update
 
 // Query transactions
 const txList = await book.listTransactions("account:'Bank' after:2024-01-01");
@@ -117,92 +115,97 @@ book.getProperty("base_currency");
 
 ```typescript
 // Transaction events
-TRANSACTION_CREATED   // Draft created
-TRANSACTION_POSTED    // Posted to accounts
-TRANSACTION_CHECKED   // Marked as reconciled
-TRANSACTION_UNCHECKED // Unmarked
-TRANSACTION_UPDATED   // Modified
-TRANSACTION_DELETED   // Trashed
-TRANSACTION_RESTORED  // Restored from trash
+TRANSACTION_CREATED; // Draft created
+TRANSACTION_POSTED; // Posted to accounts
+TRANSACTION_CHECKED; // Marked as reconciled
+TRANSACTION_UNCHECKED; // Unmarked
+TRANSACTION_UPDATED; // Modified
+TRANSACTION_DELETED; // Trashed
+TRANSACTION_RESTORED; // Restored from trash
 
 // Account events
-ACCOUNT_CREATED | ACCOUNT_UPDATED | ACCOUNT_DELETED
+ACCOUNT_CREATED | ACCOUNT_UPDATED | ACCOUNT_DELETED;
 
 // Other events
-GROUP_CREATED | GROUP_UPDATED | GROUP_DELETED
-FILE_CREATED | FILE_UPDATED
-BOOK_UPDATED | BOOK_DELETED
+GROUP_CREATED | GROUP_UPDATED | GROUP_DELETED;
+FILE_CREATED | FILE_UPDATED;
+BOOK_UPDATED | BOOK_DELETED;
 ```
 
 ### Event Handler Pattern
 
 ```typescript
-import { Hono } from 'hono';
-import { Bkper, Book } from 'bkper-js';
+import { Hono } from "hono";
+import { Bkper, Book } from "bkper-js";
 
 const app = new Hono<{ Bindings: Env }>();
 
-app.post('/events', async (c) => {
-  const event: bkper.Event = await c.req.json();
-  
-  const bkper = new Bkper({
-    oauthTokenProvider: async () => c.req.header('bkper-oauth-token'),
-    agentIdProvider: async () => c.req.header('bkper-agent-id'),
-  });
-  
-  const book = new Book(event.book, bkper.getConfig());
-  
-  switch (event.type) {
-    case 'TRANSACTION_CHECKED':
-      return c.json(await handleTransactionChecked(book, event));
-    default:
-      return c.json({ result: false });
-  }
+app.post("/events", async (c) => {
+    const event: bkper.Event = await c.req.json();
+
+    const bkper = new Bkper({
+        oauthTokenProvider: async () => c.req.header("bkper-oauth-token"),
+        agentIdProvider: async () => c.req.header("bkper-agent-id"),
+    });
+
+    const book = new Book(event.book, bkper.getConfig());
+
+    switch (event.type) {
+        case "TRANSACTION_CHECKED":
+            return c.json(await handleTransactionChecked(book, event));
+        default:
+            return c.json({ result: false });
+    }
 });
 ```
 
 ### TRANSACTION_CHECKED Handler Example
 
 ```typescript
-async function handleTransactionChecked(
-  book: Book, 
-  event: bkper.Event
-): Promise<Result> {
-  const operation = event.data.object as bkper.TransactionOperation;
-  const transaction = operation.transaction;
-
-  if (!transaction?.posted) {
-    return { result: false };
-  }
+async function handleTransactionChecked(book: Book, event: bkper.Event): Promise<Result> {
+    const operation = event.data.object as bkper.TransactionOperation;
+    const transaction = operation.transaction;
 
-  // Prevent bot loops
-  if (transaction.agentId === 'my-bot-id') {
-    return { result: false };
-  }
-
-  // Your logic here
-  console.log(`Transaction checked: ${transaction.id}`);
-  
-  return { 
-    result: `CHECKED: ${transaction.date} ${transaction.amount}` 
-  };
+    if (!transaction?.posted) {
+        return { result: false };
+    }
+
+    // Prevent bot loops
+    if (transaction.agentId === "my-bot-id") {
+        return { result: false };
+    }
+
+    // Your logic here
+    console.log(`Transaction checked: ${transaction.id}`);
+
+    return {
+        result: `CHECKED: ${transaction.date} ${transaction.amount}`,
+    };
 }
 ```
 
 ### Response Format
 
 ```typescript
 type Result = {
-  result?: string | string[] | boolean;  // Success message(s)
-  error?: string;                         // Error (red in UI)
-  warning?: string;                       // Warning (yellow in UI)
+    result?: string | string[] | boolean; // Success message(s)
+    error?: string; // Error (red in UI)
+    warning?: string; // Warning (yellow in UI)
 };
 
 // Examples
-{ result: false }                              // No action
-{ result: "CHECKED: 2024-01-15 100.00" }       // Success
-{ result: ["Book A: OK", "Book B: OK"] }       // Multiple
-{ error: "Rate not found" }                    // Error
+{
+    result: false;
+} // No action
+{
+    result: "CHECKED: 2024-01-15 100.00";
+} // Success
+{
+    result: ["Book A: OK", "Book B: OK"];
+} // Multiple
+{
+    error: "Rate not found";
+} // Error
 ```
 
 ## App Configuration (bkperapp.yaml)
@@ -229,25 +232,25 @@ webhookUrl: https://${id}.bkper.app/events
 webhookUrlDev: http://localhost:8788/events
 apiVersion: v5
 events:
-  - TRANSACTION_CHECKED
+    - TRANSACTION_CHECKED
 
 # Developer tooling
 skills:
-  autoUpdate: true
-  installed:
-    - bkper-app-dev
-    - bkper-web-dev
+    autoUpdate: true
+    installed:
+        - bkper-app-dev
+        - bkper-web-dev
 ```
 
 ### Menu URL Variables
 
-| Variable | Description |
-|----------|-------------|
-| `${book.id}` | Current book ID |
-| `${book.properties.xxx}` | Book property value |
-| `${account.id}` | Current account ID |
-| `${transactions.ids}` | Selected transaction IDs |
-| `${transactions.query}` | Current query |
+| Variable                 | Description              |
+| ------------------------ | ------------------------ |
+| `${book.id}`             | Current book ID          |
+| `${book.properties.xxx}` | Book property value      |
+| `${account.id}`          | Current account ID       |
+| `${transactions.ids}`    | Selected transaction IDs |
+| `${transactions.query}`  | Current query            |
 
 ## Common Patterns
 
@@ -256,23 +259,23 @@ skills:
 ```typescript
 // Create linked transaction
 const mirrorTx = new Transaction(connectedBook)
-  .setDate(originalTx.date)
-  .setAmount(originalTx.amount)
-  .addRemoteId(originalTx.id)  // Link to original
-  .post();
+    .setDate(originalTx.date)
+    .setAmount(originalTx.amount)
+    .addRemoteId(originalTx.id) // Link to original
+    .post();
 
 // Find linked transaction
 const linked = await book
-  .listTransactions(`remoteId:${originalTx.id}`)
-  .then(list => list.getFirst());
+    .listTransactions(`remoteId:${originalTx.id}`)
+    .then((list) => list.getFirst());
 ```
 
 ### Bot Loop Prevention
 
 ```typescript
 // Always check agentId to avoid infinite loops
 if (transaction.agentId === MY_AGENT_ID) {
-  return { result: false };
+    return { result: false };
 }
 ```
 
@@ -284,8 +287,8 @@ const collection = await book.getCollection();
 const connectedBooks = collection?.getBooks() ?? [];
 
 for (const connectedBook of connectedBooks) {
-  if (connectedBook.getId() !== book.getId()) {
-    // Process connected book
-  }
+    if (connectedBook.getId() !== book.getId()) {
+        // Process connected book
+    }
 }
 ```