nc_program_manager/.paul/phases/10-readme-docs/10-01-PLAN.md

---
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>