superme-docs

name	superme-docs
description	Use for documentary and paperwork tasks — identifying, naming, filing, verifying or tracking a document; signed PDFs and digital signatures; certificate or permit expiry; duplicate or ambiguous document versions; Spanish administrative paperwork (NIE, TIE, tasas, modelo 790, solicitudes, justificantes).

superme-docs

Paperwork is the highest-consequence, lowest-glamour part of this system. A lost signed form costs weeks; a wrong version sent to an official costs more.

Naming convention

<WHAT>_<WHO>_<STATE>_<YYYY-MM-DD>.pdf
AUTORIZACION_TITULARES_<Name>_FIRMADO_2026-07-30.pdf
CERT_FNMT_<SURNAME>_<NIE>_CADUCA-2028-12-31.p12

Certificates and permits carry their expiry in the filename (CADUCA-). It survives being moved, mailed and re-downloaded, and it is readable without opening the file.

The version hazard

Two files with the same name and different content is the dangerous case — more dangerous than a plain duplicate. The live scan found two files with an identical name ending - COMPLETED.pdf, one 605 KB and one 258 KB. Both claim to be completed. Only one can be the one to submit.

When this appears:

1. Do not delete anything.
2. Establish which is authoritative — signature present, date, page count.
3. Record the winner in a document entity with file: pointing at it.
4. Mark the loser status: superseded so it stops surfacing.

~/Desktop/email/README.md records the same lesson from a near-miss: never discriminate between near-identical documents by subject or filename alone. Use something unique — byte size, character count, signature block.

Signing a PDF with the FNMT certificate

superme signs PDFs with the user's FNMT digital certificate via AutoFirma (PAdES), the same mechanism the residence paperwork used.

superme doctor            # auto-scans: reports "digital signature: ready — <alias>"
superme sign --selftest   # signs a throwaway PDF to prove signing works end-to-end
superme sign <file.pdf>   # sign a real document → <file>_FIRMADO.pdf

The alias is auto-detected from the keychain (java -jar autofirma.jar listaliases -store mac). It is lowercase (surname firstname - <nie>); the keychain's uppercase display name is NOT the alias — matching against the display name is the mistake that makes signing report "no entry with that alias". Signing verifies the output actually carries a signature before reporting success — a zero exit code alone is not proof.

Signing is never automatic. It applies the user's legal identity, so sign_document is in smlib.NEVER_AUTO: no cycle, no whitelist rule can ever sign. Only an explicit superme sign — a human decision — signs anything. Never sign a document the user has not clearly asked to sign.

Verifying a signed PDF

pdfsig document.pdf                 # signature presence, signer CN, CMS verification
ls -l document.pdf                  # size, to distinguish near-identical copies

Check before sending: the signer CN matches, CMS verification succeeds, and the visible text carries the right identifier. A signature that validates on a document showing the wrong NIE is still the wrong document.

Tracking expiry

Register anything with an expiry as a document with expires:. It then generates its own deadline within 90 days — no hand-written todo needed. When it is renewed, set the old one's status: superseded and register the new one.

Some renewals carry constraints worth writing in the body. The FNMT certificate renewed 2026-08-03 is valid to 2028-12-31, and the 2028 renewal must be done in person — that constraint is the reason the document is tracked rather than merely filed.

Filing

Documents stay where they live — a permits folder, a reimbursement folder. The database records file: paths. superme does not build a parallel copy of a document tree it does not own.