@nomad-e/bluma-cli 0.1.58 → 0.1.60

package/README.md

@@ -6,6 +6,8 @@
 
 **BluMa** is a CLI-based model agent for advanced software engineering workflows. Built with React/Ink 5, it provides an interactive terminal interface for LLM-powered automation, code generation, refactoring, and task execution. Features persistent sessions, contextual reasoning, smart feedback, coordinator mode for worker orchestration, and extensible tools/skills architecture.
 
+> **Credit:** BluMa was conceived and architected by **Alex Fonseca**.
+
 **Current Version:** 0.1.55
 
 ---
@@ -295,8 +297,8 @@ BluMa includes **40+ built-in tools** organized by category:
 | `task_get` | Get one task by id |
 | `task_update` | Update task fields |
 | `task_stop` | Cancel a task |
-| `create_artifact` | Save documents to `~/.bluma/artifacts/` |
-| `read_artifact` | Retrieve saved artifacts |
+| `create_artifact` | Save documents under `<workspace>/.bluma/artifacts/<session>/` (see `task_boundary` → `artifacts_dir`) |
+| `read_artifact` | Read artifacts from the current session directory under `.bluma/artifacts/` |
 
 ### Knowledge & Research
 | Tool | Description |
@@ -777,7 +779,7 @@ Apache 2.0 — see [LICENSE](LICENSE) for details.
 
 - **Issues**: [GitHub Issues](https://github.com/nomad-e/bluma-cli/issues)
 - **Documentation**: This README + `docs/` directory
-- **Author**: Alex Fonseca
+- **Author & Architect**: Alex Fonseca (conceived and architected BluMa)
 - **npm Package**: [@nomad-e/bluma-cli](https://www.npmjs.com/package/@nomad-e/bluma-cli)
 
 ### Runtime Modules (v0.1.41+)

package/dist/config/native_tools.json

@@ -252,7 +252,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Optional file paths (absolute) to deliver as artifacts/attachments. In sandbox mode, put generated files under ./artifacts/ and include full paths here."
+              "description": "Optional file paths (absolute) to deliver as attachments. Put generated files under ./.bluma/artifacts/ (or paths returned by task_boundary / create_artifact); never a top-level ./artifacts/ folder — tools remap that to .bluma/artifacts/."
             }
           },
           "required": [
@@ -701,7 +701,7 @@
       "type": "function",
       "function": {
         "name": "create_artifact",
-        "description": "Create or update an artifact file in the artifacts directory (~/.bluma/artifacts/). Use this to save implementation plans, walkthroughs, notes, or any document the user should review. Supports markdown files.",
+        "description": "Create or update an artifact under the workspace .bluma/artifacts/<session>/ directory (see task_boundary artifacts_dir). Use for plans, walkthroughs, notes, or deliverables. Not the same as ~/.bluma.",
         "parameters": {
           "type": "object",
           "properties": {
@@ -725,7 +725,7 @@
       "type": "function",
       "function": {
         "name": "read_artifact",
-        "description": "Read an existing artifact file from the artifacts directory. Use this to retrieve previously saved plans, walkthroughs, or notes.",
+        "description": "Read an artifact from the current session artifacts directory (.bluma/artifacts/<session>/). Use to retrieve plans or notes saved with create_artifact in this task.",
         "parameters": {
           "type": "object",
           "properties": {

package/dist/config/skills/git-pr/SKILL.md

@@ -104,7 +104,7 @@ feat(pdf): add CSV-to-PDF report generation
 
 Implement create_report.py script that reads CSV data and produces
 a formatted PDF report using reportlab. Supports custom titles and
-outputs to the artifacts directory.
+outputs to `.bluma/artifacts/` in the workspace.
 
 - Added scripts/create_report.py with argparse CLI
 - Table styling with header highlighting and grid borders

package/dist/config/skills/pdf/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: pdf
 description: >
-  Use this skill for any task involving PDF files. Triggers include: creating
-  new PDFs from scratch, reading or extracting text and tables from PDFs,
-  merging or splitting PDFs, rotating pages, adding watermarks, encrypting or
-  decrypting PDFs, filling PDF forms, extracting images, and OCR on scanned
-  PDFs. Use whenever the user mentions .pdf, "create a report", "generate a
-  document", "extract from PDF", "merge PDFs", or any PDF-related task.
+  Use for any PDF task. For **new business/executive reports**, prefer
+  `create_report.py --from-json`: invest effort in **rich, well-structured JSON**
+  (clear sections, tight copy, sparse callouts, scannable tables) — the template
+  already supplies a **modern, restrained** layout; shallow JSON wastes that
+  design. Ad-hoc ReportLab snippets produce amateur PDFs. Also: extract/merge/
+  OCR/forms. Triggers: .pdf, relatório, report, generate document, merge PDF.
 license: Proprietary. LICENSE.txt has complete terms
 ---
 
@@ -18,6 +18,114 @@ license: Proprietary. LICENSE.txt has complete terms
 > design agency, not a script. Typography, spacing, color, and hierarchy are
 > not optional — they are the foundation of a credible document.
 
+## MANDATORY workflow — new multi-page reports (read first)
+
+Ad-hoc 30-line ReportLab scripts are the #1 cause of “cheap PDF” output (no
+cover hierarchy, ugly tables, random margins). **Do not do that** for anything
+the user will share externally.
+
+**Preferred (deliverable quality locked in):**
+
+1. Build a UTF-8 JSON file with `title`, optional `subtitle` / `author`, and
+   `sections[]` (`num`, `title`, `blocks[]`). Follow the **JSON quality**
+   section below — not only the schema (see **Available Scripts** for types).
+2. Run: `python /absolute/path/to/scripts/create_report.py --from-json
+   your.json --output .bluma/artifacts/your.pdf` (or the path in `artifacts_dir` from `task_boundary`)
+3. Attach that **absolute** path as the deliverable. Do **not** paste huge
+   ReportLab source into the chat unless the user explicitly wants code.
+
+**Acceptable alternative:** copy `create_report.py` and edit only data / story
+assembly — keep the same colors, margins, `cover_story`, `section`, `pro_table`,
+`callout`, and `onFirstPage` / `onLaterPages` callbacks.
+
+**Hard no (reads as unprofessional):** default ReportLab styles; wall of text
+with no cover; tables without a styled header row; margins under 2cm; emoji in
+corporate PDFs (font/rendering inconsistency); “nota rodapé” as raw
+`canvas.drawString` for body paragraphs instead of `Paragraph` styles.
+
+## JSON quality — make the PDF look “designed”, not “filled in”
+
+The `--from-json` pipeline already applies a **clean, modern, understated**
+visual system (slate palette, one accent, generous margins, one chapter per
+page by default). **Exaggerated styling is not available and not desired** —
+quality comes from **editorial structure and copy**, not from shouting.
+
+When you author JSON, treat it like briefing a human designer:
+
+### Cover metadata (`title`, `subtitle`, `author`)
+
+- **`title`**: specific and scannable (e.g. “Relatório de atividade — Agiweb”),
+  not a generic “Relatório”. Length is OK; the script balances line breaks.
+- **`subtitle`**: one line that states **scope or period** (what this PDF is
+  for). Avoid marketing fluff.
+- **`author`**: organisation or product name the reader recognises; avoid
+  “Generated by AI” unless the user asked for it.
+
+### Sections (`num`, `title`, `blocks`)
+
+- Aim for **roughly 4–8 sections** for a typical executive note; merge thin
+  sections instead of many one-paragraph chapters.
+- **Section titles**: concrete noun phrases (“Módulos ativos”, “Estado
+  operacional”) — not “Parte 2” or “Informações”.
+- **Order inside a section** (good rhythm):
+  1. One or two **`paragraph`** blocks that set context (2–4 short sentences,
+     one main idea each; use `\n` only for a deliberate second paragraph).
+  2. Optionally an **`h2`** for a sub-topic if the section has two distinct
+     ideas.
+  3. **`bullets`** or **`table`** — not both back-to-back unless the second is
+     clearly “detail” after the first.
+  4. At most **one `callout`** per section, only for a decision, risk, or
+     single takeaway — not for every bullet.
+
+### `paragraph`
+
+- Prefer **facts, numbers, names** over vague adjectives (“significativo”,
+  “muito importante”). Write in the **same language** as the user’s request.
+- Do not paste huge URLs or stack traces; summarise.
+
+### `bullets`
+
+- **Parallel wording** (all start with a verb, or all are noun phrases).
+- **~3–8 items** per list in the body; move long enumerations to a **table** or
+  an appendix section.
+- One line per item when possible; trim redundant words.
+
+### `table`
+
+- Prefer **2–5 columns**; headers are **short labels** (“Módulo”, “Estado”, not
+  sentences).
+- Rows must be **readable at a glance**; paraphrase long statuses instead of
+  dumping raw log lines.
+- Omit `col_widths` unless you need to weight columns; the generator normalises
+  widths.
+
+### `callout` (`variant`: `info` | `warning`)
+
+- **Info**: synthesis, definition, or “how to read this document”.
+- **Warning**: real risk, compliance, or “requires action” — not routine stats.
+- **Title**: 2–5 words; **text**: 1–3 sentences. **Never** stack two callouts in
+  a row.
+
+### `h2`
+
+- Use sparingly inside long sections; keeps hierarchy without visual noise.
+
+### `page_break_per_section`
+
+- Default **`true`** for multi-topic reports (calm, one chapter per page).
+- Set **`false`** only for a short, single-thread document where breaks would
+  feel wasteful.
+
+### Restraint checklist (before you run the script)
+
+- [ ] Every section has at least one **substantive** `paragraph`, not only
+  bullets.
+- [ ] No more than **one callout** per section unless the user explicitly wants
+  more.
+- [ ] Tables are **small and meaningful**; no “spreadsheet dump”.
+- [ ] No duplicated content between sumário-level titles and body.
+- [ ] Tone is **professional and calm** — the layout already carries authority.
+
 ## MANDATORY: Professional Style System
 
 Every PDF you create MUST use a consistent design system. Define these at the
@@ -29,17 +137,19 @@ top of every script BEFORE building any content.
 from reportlab.lib.colors import HexColor
 
 COLORS = {
-    'primary':    HexColor('#1B2A4A'),  # Dark navy — titles, headers
-    'secondary':  HexColor('#2C5F8A'),  # Steel blue — subtitles, accents
-    'accent':     HexColor('#E67E22'),  # Warm orange — highlights, callouts
-    'text':       HexColor('#2D3436'),  # Near-black — body text
-    'text_light': HexColor('#636E72'),  # Gray — captions, footnotes
-    'bg_light':   HexColor('#F8F9FA'),  # Light gray — callout backgrounds
-    'bg_accent':  HexColor('#EBF5FB'),  # Light blue — info boxes
-    'border':     HexColor('#BDC3C7'),  # Subtle border
+    # Keep in sync with scripts/create_report.py when editing custom code
+    'primary':    HexColor('#0F172A'),  # Slate — titles, table headers
+    'secondary':  HexColor('#334155'),  # Slate — subtitles, rules
+    'accent':     HexColor('#C2410C'),  # Burnt orange — rules, emphasis
+    'muted':      HexColor('#64748B'),
+    'text':       HexColor('#1E293B'),
+    'text_light': HexColor('#64748B'),
+    'bg_light':   HexColor('#F1F5F9'),
+    'bg_accent':  HexColor('#E0F2FE'),
+    'border':     HexColor('#CBD5E1'),
     'white':      HexColor('#FFFFFF'),
-    'success':    HexColor('#27AE60'),  # Green — positive indicators
-    'danger':     HexColor('#E74C3C'),  # Red — warnings
+    'success':    HexColor('#15803D'),
+    'danger':     HexColor('#B91C1C'),
 }
 ```
 
@@ -272,11 +382,11 @@ def add_section(story, number, title):
 def add_callout(story, title, text, box_type='info'):
     bg = COLORS['bg_accent'] if box_type == 'info' else COLORS['bg_light']
     border = COLORS['secondary'] if box_type == 'info' else COLORS['accent']
-    icon = '💡' if box_type == 'info' else '⚠️'
+    label = 'Information' if box_type == 'info' else 'Warning'
 
     content = [
         [Paragraph(
-            f"<b>{icon} {title}</b>",
+            f"<b>{label} — {title}</b>",
             ParagraphStyle('CalloutTitle', fontName=FONT_BOLD,
                            fontSize=10, textColor=COLORS['primary'],
                            spaceAfter=4)
@@ -384,8 +494,12 @@ add_table(story,
     [['Revenue', '$1.2M', '+15%'], ['Users', '50K', '+22%']],
 )
 
-doc.build(story, onFirstPage=lambda c, d: None,
-          onLaterPages=header_footer)
+def cover_canvas(canvas_obj, doc):
+    """Page 1 only: brand bar / rules. See create_report.py draw_cover_canvas."""
+    pass
+
+# First page = cover art; later pages = header + footer
+doc.build(story, onFirstPage=cover_canvas, onLaterPages=header_footer)
 ```
 
 ## Design Rules (MANDATORY)
@@ -399,7 +513,9 @@ doc.build(story, onFirstPage=lambda c, d: None,
 7. **Spacing**: Generous whitespace. Use `Spacer` between sections
 8. **Cover page**: Every document with 3+ pages MUST have a cover page
 9. **Headers/Footers**: Every multi-page document MUST have page numbers
-10. **No raw `drawString`**: Use `Paragraph` with styles for all text
+10. **Body text**: use `Paragraph` + styles, never raw `drawString` for
+    paragraphs. **Exception:** minimal `drawString` in `onFirstPage` /
+    `onLaterPages` canvas callbacks for running title and page numbers only.
 11. **Alignment**: Body text justified, titles centered, code left-aligned
 12. **Callout boxes**: Use for key insights, warnings, important notes
 13. **Section dividers**: Use `HRFlowable` or colored bars between major sections
@@ -498,5 +614,20 @@ for i, img in enumerate(images):
 
 ## Available Scripts
 
-- create_report.py: Professional report template with cover, TOC, styled sections
+- **create_report.py** — default: demo PDF; **production:** `--from-json FILE`
+  - Before writing JSON, follow **“JSON quality”** (this file) so content matches
+    the clean template — schema alone is not enough.
+  - Schema (top-level keys): `title` (str), `subtitle` (optional str),
+    `author` (optional str), `page_break_per_section` (optional bool, default
+    `true` — cada capítulo começa em página nova), `sections` (array).
+  - Each section: `num` (int), `title` (str), `blocks` (array).
+  - Each block: `type` is one of:
+    - `paragraph` — `{ "type": "paragraph", "text": "..." }` (use `\n` for line breaks)
+    - `h2` — `{ "type": "h2", "text": "..." }`
+    - `callout` — `{ "type": "callout", "title": "...", "text": "...", "variant": "info"|"warning" }`
+    - `bullets` — `{ "type": "bullets", "items": ["...", "..."] }`
+    - `table` — `{ "type": "table", "headers": [...], "rows": [[...],...], "col_widths": null or [pt,...] }`
+    - `spacer` — `{ "type": "spacer", "pt": 12 }`
+  - Plain text in JSON is XML-escaped automatically; do not embed ReportLab HTML
+    unless you generate JSON from trusted code that already escapes markup.
 - merge_pdfs.py: Merge multiple PDFs into one