docs(10-readme-docs): Italian README for NcProgramManager

Operator-facing README covering CLI args, license setup, supported controllers, and NC validation. PAUL phase 10 complete. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-17 23:46:50 +02:00 · 2026-05-17 23:46:50 +02:00 · 718c3ce8da
commit 718c3ce8da
parent 15644cfdf8
6 changed files with 386 additions and 14 deletions
--- a/.paul/ROADMAP.md
+++ b/.paul/ROADMAP.md
@ -117,4 +117,17 @@ Completed: 2026-05-17
 **Plans:** [x] 09-01: LicenseGenerator standalone tool + real public key embedded

 ---
-*Roadmap updated: 2026-05-17 — v0.2 NcProgramManager complete (all 4 phases)*
+
+## Standalone Phases (post-v0.2)
+
+| Phase | Name | Plans | Status |
+|-------|------|-------|--------|
+| 10 | readme-docs | 1 | ✅ Complete | 2026-05-17 |
+
+### Phase 10: readme-docs ✅
+**Goal:** Write Italian README for NcProgramManager and LicenseGenerator repos — describe what each does, prerequisites, setup, CLI usage, license workflow.
+**Depends on:** Phase 09 (license workflow complete)
+**Plans:** [x] 10-01: Italian READMEs for both repos
+
+---
+*Roadmap updated: 2026-05-17 — Phase 10 readme-docs complete. Project fully documented.*
--- a/.paul/STATE.md
+++ b/.paul/STATE.md
@ -5,25 +5,26 @@
 See: .paul/PROJECT.md (updated 2026-05-17)

 **Core value:** Machinists transfer CNC programs to/from any controller without manual steps or internet
-**Current focus:** v0.2 complete — offline license system fully shipped
+**Current focus:** All phases complete — project fully documented

 ## Current Position

 Milestone: v0.2 NcProgramManager — COMPLETE
-Phase: 4 of 4 (09-license-generator) — Complete
-Plan: 09-01 complete
-Status: Milestone v0.2 complete. Ready to plan next milestone or ship.
-Last activity: 2026-05-17 — Phase 09 license-generator complete (UNIFY done)
+Phase: 10 (readme-docs) — Complete
+Plan: 10-01 complete
+Status: All phases done. Project complete.
+Last activity: 2026-05-17 — Italian READMEs written for both repos

 Progress:
 - Milestone v0.1: [██████████] 100% (complete)
 - Milestone v0.2: [██████████] 100% (complete)
+- Phase 10 (readme-docs): [██████████] 100% (complete)

 ## Loop Position

 ```
 PLAN ──▶ APPLY ──▶ UNIFY
-  ✓        ✓        ✓     [Loop complete — milestone v0.2 done]
+  ✓        ✓        ✓     [Loop complete — project fully documented]
 ```

 ## What Was Built (v0.1 Multi-CN Release)
@ -83,6 +84,10 @@ PLAN ──▶ APPLY ──▶ UNIFY
 - Real public key embedded in `Licensing/LicenseValidator.cs` (PLACEHOLDER removed)
 - `private.key.xml` at `~/Documents/mine/c#/LicenseGenerator/` (gitignored — keep secure)

+### Phase 10 — README Docs
+- `README.md` in NcProgramManager root — Italian, operator-facing: CLI args, license setup, examples, controllers table
+- `README.md` in LicenseGenerator repo — Italian, vendor-facing: keygen first-run, 4-step license issuance workflow, commands table, security
+
 ## CLI Args (current)
 - `-manufacturer=fanuc|heidenhain|siemens|mitsubishi` (default: fanuc)
 - `-azione=` — action (Scarica/Invia/etc.)
@ -114,7 +119,7 @@ PLAN ──▶ APPLY ──▶ UNIFY
 - `private.key.xml` owned by root — run `sudo chown $USER ~/Documents/mine/c#/LicenseGenerator/private.key.xml`

 ### Blockers/Concerns
-None — v0.2 milestone complete.
+None — project complete.

 ### Git State
 Last commit (NcProgramManager): see `git log --oneline`
@ -124,9 +129,9 @@ Branch: main
 ## Session Continuity

 Last session: 2026-05-17
-Stopped at: v0.2 milestone complete (Phase 09 UNIFY done)
-Next action: Plan next milestone or ship v0.2
-Resume file: .paul/ROADMAP.md
+Stopped at: Phase 10 complete — all phases done
+Next action: git commit docs(10-readme-docs), then project is fully shipped
+Resume file: .paul/phases/10-readme-docs/10-01-SUMMARY.md

 ---
 *STATE.md — Updated after every significant action*
--- a/.paul/paul.json
+++ b/.paul/paul.json
@ -7,8 +7,8 @@
    "status": "complete"
  },
  "phase": {
-    "number": 9,
-    "name": "license-generator",
+    "number": 10,
+    "name": "readme-docs",
    "status": "complete"
  },
  "loop": {
@ -17,7 +17,7 @@
  },
  "timestamps": {
    "created_at": "2026-05-13T00:00:00Z",
-    "updated_at": "2026-05-17T23:45:00Z"
+    "updated_at": "2026-05-17T00:00:00Z"
  },
  "satellite": {
    "groom": true
--- a/.paul/phases/10-readme-docs/10-01-PLAN.md
+++ b/.paul/phases/10-readme-docs/10-01-PLAN.md
@ -0,0 +1,194 @@
+---
+phase: 10-readme-docs
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - README.md
+  - ~/Documents/mine/c#/LicenseGenerator/README.md
+autonomous: true
+---
+
+<objective>
+## Goal
+Write Italian-language README for both repos: NcProgramManager (operator-facing — what it does, CLI args, license setup) and LicenseGenerator (vendor-facing — key pair generation, license issuance workflow).
+
+## Purpose
+Operators and integrators need setup and usage docs in Italian. The license workflow spans both tools, so each README must describe its role in the full chain.
+
+## Output
+- `README.md` in NcProgramManager repo root
+- `README.md` in LicenseGenerator repo root (`~/Documents/mine/c#/LicenseGenerator/`)
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/STATE.md
+
+## Source Files
+@Licensing/LicenseValidator.cs
+@Program.cs
+@InputArgs.cs
+</context>
+
+<acceptance_criteria>
+
+## AC-1: NcProgramManager README covers all CLI args and license setup
+```gherkin
+Given an operator reading NcProgramManager/README.md
+When they follow the instructions
+Then they can place license.lic next to the EXE and run the tool with correct args for their CNC manufacturer
+```
+
+## AC-2: LicenseGenerator README covers full vendor license issuance workflow
+```gherkin
+Given a vendor reading LicenseGenerator/README.md
+When they follow the instructions
+Then they can run keygen once, get fingerprint from customer machine, sign and deliver license.lic
+```
+
+## AC-3: Both READMEs written in Italian
+```gherkin
+Given either README
+When read by an Italian-speaking user
+Then all prose, section headers, and instructions are in Italian (technical terms and CLI args remain in English)
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Write NcProgramManager README in Italian</name>
+  <files>README.md</files>
+  <action>
+    Create `README.md` at NcProgramManager repo root. Italian prose throughout. Keep CLI args, file names, and code blocks in English.
+
+    **Sections:**
+
+    **# NcProgramManager**
+    One-paragraph description: software per trasferire programmi CNC da/verso controller (Fanuc FOCAS, Heidenhain LSV2, Siemens Sinumerik, Mitsubishi FTP). Console EXE Windows, funziona offline.
+
+    **## Requisiti**
+    - Windows (qualsiasi versione che supporti .NET 4.7.2)
+    - .NET Framework 4.7.2 installato
+    - File `license.lic` valido (rilasciato dal fornitore)
+
+    **## Licenza**
+    Explain: place `license.lic` in same folder as `NcProgramManager.exe`. Without it, software refuses to start. To obtain license: contact vendor with machine fingerprint (obtained via LicenseGenerator fingerprint command).
+
+    **## Utilizzo**
+    Show CLI arg table:
+    | Parametro | Valori | Descrizione |
+    | `-manufacturer=` | `fanuc` / `heidenhain` / `siemens` / `mitsubishi` | Tipo di controller (default: fanuc) |
+    | `-azione=` | `Scarica` / `Invia` / ... | Azione da eseguire |
+    | `-ip=` | indirizzo IP | IP del controller CNC |
+    | `-porta=` | numero porta | Porta di connessione |
+    | `-username=` | nome utente | Solo per Heidenhain/Siemens/Mitsubishi |
+    | `-password=` | password | Solo per Heidenhain/Siemens/Mitsubishi |
+
+    **## Esempi**
+    Show 2-3 concrete examples with real-looking args for Fanuc and Heidenhain.
+
+    **## Controller supportati**
+    Brief table: Fanuc (FOCAS, 32-bit DLL), Heidenhain (LSV2, porta 19000), Siemens Sinumerik (FTP, `/_N_MPF_DIR/`), Mitsubishi (FTP, porta 21, `/PRG/`).
+
+    **## Validazione programma NC**
+    One paragraph: before upload, NcProgramManager validates the NC program. Errors block the transfer. Warnings are logged but don't block.
+
+    Avoid: mentioning internal class names, test infrastructure, or implementation details.
+  </action>
+  <verify>
+    `cat README.md` — file exists, has all sections, Italian prose, CLI table present.
+    `grep "\-manufacturer" README.md` → match found.
+  </verify>
+  <done>AC-1 and AC-3 satisfied: README covers CLI args, license setup, all in Italian.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Write LicenseGenerator README in Italian</name>
+  <files>~/Documents/mine/c#/LicenseGenerator/README.md</files>
+  <action>
+    Create `README.md` at LicenseGenerator repo root. Vendor-facing — assumes technical user. Italian prose. Keep commands and file names in English.
+
+    **Sections:**
+
+    **# LicenseGenerator**
+    One-paragraph description: strumento per il fornitore per generare coppie di chiavi RSA e firmare le licenze per NcProgramManager. Non va distribuito ai clienti.
+
+    **## Requisiti**
+    - `keygen` e `sign`: .NET 4.7.2 (Windows) o Mono 6+ (Linux/Mac)
+    - `fingerprint`: Windows obbligatorio (usa WMI)
+
+    **## Primo avvio — Generazione della coppia di chiavi**
+    Step-by-step:
+    1. Run `LicenseGenerator.exe keygen`
+    2. Saves `private.key.xml` in current dir — **mantenere segreto, non condividere mai**
+    3. Prints public key XML to stdout — copy and paste into `LicenseValidator.cs` (field `PublicKeyXml`) and recompile NcProgramManager
+
+    Warn clearly: if private.key.xml is lost, must generate a new key pair and re-ship NcProgramManager with new public key.
+
+    **## Workflow per emettere una licenza**
+    Numbered steps:
+    1. Il cliente esegue `LicenseGenerator.exe fingerprint` sulla macchina di destinazione (Windows) e invia il testo stampato al fornitore
+    2. Il fornitore esegue: `LicenseGenerator.exe sign -key=private.key.xml -fingerprint=<testo-cliente> -out=license.lic`
+    3. Il fornitore invia `license.lic` al cliente
+    4. Il cliente copia `license.lic` nella stessa cartella di `NcProgramManager.exe`
+
+    **## Comandi**
+    Table:
+    | Comando | Descrizione |
+    | `LicenseGenerator.exe keygen` | Genera coppia RSA 2048-bit. Salva `private.key.xml`, stampa chiave pubblica XML |
+    | `LicenseGenerator.exe fingerprint` | Legge l'impronta hardware della macchina (solo Windows) |
+    | `LicenseGenerator.exe sign -key=<file> -fingerprint=<fp> [-out=<file.lic>]` | Firma l'impronta e scrive il file licenza |
+
+    **## Sicurezza**
+    Short section: `private.key.xml` must never be committed to git (already in .gitignore), never shared with customers, stored securely. Anyone with the private key can forge licenses.
+
+    Avoid: mentioning internal C# class names, RSA algorithm details, or test setup.
+  </action>
+  <verify>
+    `cat ~/Documents/mine/c#/LicenseGenerator/README.md` — exists, has all sections.
+    `grep "fingerprint" ~/Documents/mine/c#/LicenseGenerator/README.md` → match found.
+  </verify>
+  <done>AC-2 and AC-3 satisfied: README covers keygen, fingerprint, sign workflow, all in Italian.</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- Any `.cs` source files in either repo
+- `.paul/` directory contents (except this plan's phase files)
+- `NcProgramManager.sln`, `LicenseGenerator.sln`, any `.csproj`
+
+## SCOPE LIMITS
+- Italian prose only — no English prose outside of technical terms, CLI args, code blocks
+- No code changes in either repo
+- Do not add build instructions (not relevant for end users — binary is distributed)
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] `README.md` exists at NcProgramManager repo root
+- [ ] `~/Documents/mine/c#/LicenseGenerator/README.md` exists
+- [ ] Both files contain Italian prose
+- [ ] NcProgramManager README has CLI arg table with all 6 args
+- [ ] LicenseGenerator README has numbered license issuance workflow
+- [ ] Both READMEs mention `license.lic`
+</verification>
+
+<success_criteria>
+- Both READMEs written and saved
+- Italian throughout (technical terms/commands in English)
+- Operator can follow NcProgramManager README to set up and run the tool
+- Vendor can follow LicenseGenerator README to issue a license
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/10-readme-docs/10-01-SUMMARY.md`
+</output>
--- a/.paul/phases/10-readme-docs/10-01-SUMMARY.md
+++ b/.paul/phases/10-readme-docs/10-01-SUMMARY.md
@ -0,0 +1,93 @@
+---
+phase: 10-readme-docs
+plan: 01
+subsystem: docs
+tags: [readme, italian, license, cli]
+
+requires:
+  - phase: 09-license-generator
+    provides: keygen/fingerprint/sign commands and full license workflow
+
+provides:
+  - Italian README for NcProgramManager (operator-facing)
+  - Italian README for LicenseGenerator (vendor-facing)
+
+affects: []
+
+tech-stack:
+  added: []
+  patterns: []
+
+key-files:
+  created:
+    - README.md
+    - ~/Documents/mine/c#/LicenseGenerator/README.md
+  modified: []
+
+key-decisions:
+  - "Italian prose throughout; technical terms, CLI args, file names, code blocks in English"
+
+patterns-established: []
+
+duration: ~5min
+started: 2026-05-17T00:00:00Z
+completed: 2026-05-17T00:00:00Z
+---
+
+# Phase 10 Plan 01: readme-docs Summary
+
+**Italian README written for both repos: NcProgramManager (operator — CLI args, license setup) and LicenseGenerator (vendor — keygen, fingerprint, sign workflow).**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~5 min |
+| Started | 2026-05-17 |
+| Completed | 2026-05-17 |
+| Tasks | 2 completed |
+| Files modified | 2 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: NcProgramManager README covers all CLI args and license setup | Pass | All 6 args in table; license.lic placement explained |
+| AC-2: LicenseGenerator README covers full vendor license issuance workflow | Pass | 4-step numbered workflow; keygen/fingerprint/sign commands documented |
+| AC-3: Both READMEs written in Italian | Pass | Italian prose throughout; technical terms/commands in English |
+
+## Accomplishments
+
+- NcProgramManager README: description, requirements, license setup, 6-arg CLI table, 3 examples (Fanuc/Heidenhain/Siemens), supported controllers table, NC validation note
+- LicenseGenerator README: vendor-only framing, keygen first-run steps, 4-step license issuance workflow, commands table, security section
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `README.md` | Created | Operator-facing Italian docs for NcProgramManager |
+| `~/Documents/mine/c#/LicenseGenerator/README.md` | Created | Vendor-facing Italian docs for LicenseGenerator |
+
+## Decisions Made
+
+None — followed plan as specified.
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Issues Encountered
+
+None.
+
+## Next Phase Readiness
+
+**Ready:** Both repos fully documented. Project complete.
+
+**Concerns:** None.
+
+**Blockers:** None.
+
+---
+*Phase: 10-readme-docs, Plan: 01*
+*Completed: 2026-05-17*
--- a/README.md
+++ b/README.md
@ -0,0 +1,67 @@
+# NcProgramManager
+
+Software per il trasferimento di programmi CNC da e verso controller di macchine utensili. Supporta Fanuc (FOCAS), Heidenhain (LSV2), Siemens Sinumerik (FTP) e Mitsubishi (FTP). Funziona completamente offline come applicazione console per Windows.
+
+## Requisiti
+
+- Windows (qualsiasi versione compatibile con .NET Framework 4.7.2)
+- .NET Framework 4.7.2 installato
+- File `license.lic` valido (rilasciato dal fornitore)
+
+## Licenza
+
+Copiare il file `license.lic` nella stessa cartella dell'eseguibile `NcProgramManager.exe`. Senza licenza valida il programma si chiude all'avvio.
+
+Per ottenere una licenza contattare il fornitore fornendo l'impronta hardware della macchina. L'impronta si ottiene eseguendo il comando `fingerprint` dello strumento `LicenseGenerator.exe` sulla macchina di destinazione.
+
+## Utilizzo
+
+```
+NcProgramManager.exe -manufacturer=<tipo> -azione=<azione> -ip=<ip> -porta=<porta> [opzioni]
+```
+
+### Parametri
+
+| Parametro | Valori | Descrizione |
+|-----------|--------|-------------|
+| `-manufacturer=` | `fanuc` / `heidenhain` / `siemens` / `mitsubishi` | Tipo di controller CNC (predefinito: `fanuc`) |
+| `-azione=` | `Scarica` / `Invia` / ... | Azione da eseguire |
+| `-ip=` | indirizzo IP | Indirizzo IP del controller CNC |
+| `-porta=` | numero porta | Porta di connessione |
+| `-username=` | nome utente | Solo per Heidenhain, Siemens, Mitsubishi |
+| `-password=` | password | Solo per Heidenhain, Siemens, Mitsubishi |
+
+La licenza viene letta automaticamente dal file `license.lic` nella cartella dell'eseguibile — nessun parametro aggiuntivo richiesto.
+
+## Esempi
+
+Scarica programma da controller Fanuc:
+
+```
+NcProgramManager.exe -manufacturer=fanuc -azione=Scarica -ip=192.168.1.100 -porta=8193
+```
+
+Invia programma a controller Heidenhain:
+
+```
+NcProgramManager.exe -manufacturer=heidenhain -azione=Invia -ip=192.168.1.50 -porta=19000 -username=operator -password=secret
+```
+
+Scarica programma da Siemens Sinumerik:
+
+```
+NcProgramManager.exe -manufacturer=siemens -azione=Scarica -ip=192.168.1.200 -porta=21 -username=admin -password=secret
+```
+
+## Controller supportati
+
+| Produttore | Protocollo | Porta predefinita | Note |
+|------------|------------|-------------------|------|
+| Fanuc | FOCAS (DLL 32-bit) | 8193 | Richiede `fwlib32.dll` nella stessa cartella |
+| Heidenhain | LSV2 (TCP) | 19000 | Testato su TNC series |
+| Siemens | FTP | 21 | Directory programmi: `/_N_MPF_DIR/` — richiede opzione FTP abilitata sul Sinumerik |
+| Mitsubishi | FTP | 21 | Directory programmi: `/PRG/` |
+
+## Validazione del programma NC
+
+Prima di inviare un programma al controller, NcProgramManager esegue una validazione automatica del codice NC. Gli errori bloccano il trasferimento. Gli avvisi vengono registrati ma non interrompono l'operazione.