Epic: complete the LibreCode brand system

[vitormattos]

Epic: complete the LibreCode brand system

This issue is the root continuity issue for finishing the LibreCode brand repository. A new contributor, maintainer, or AI agent should be able to start here, inspect the linked repository material, and continue the work without relying on prior chat history.

The repository itself is the source of truth. Use LibreSign/brand only as an implementation reference for engineering quality, accessibility, maintainability, licensing organization, and release process. Do not copy LibreSign-specific brand decisions into LibreCode.

Start here

When resuming this work:

1. read this issue completely;
2. inspect the current main branch before making changes;
3. read PR Record LibreCode brand completion plan from LibreSign lessons #8 / docs/libresign-parity-plan.md once merged;
4. inspect issues Finish reproducible brand manual and release process #3, Verify and document trademark registrations #4, and Apply canonical repository metadata #6;
5. inspect current CI status and open pull requests;
6. compare the current implementation with LibreSign/brand only where this issue explicitly asks for architecture or quality parity;
7. work in small reviewable pull requests;
8. preserve DCO sign-off on every human-authored commit;
9. do not create the first stable release until external homologation is explicitly complete.

If PR #8 is still open, its content is nevertheless the intended completion plan; do not lose or overwrite that context.

Current baseline

Already present:

• canonical Git repository;
• naming/pronunciation baseline;
• canonical SVG artwork;
• colors and typography;
• Typst manual source;
• reproducible asset generation baseline;
• PDF/UA-1 compile target;
• CI manual build;
• release workflow for v*;
• CC BY-SA 4.0 for documentation/artwork;
• AGPL-3.0-or-later for automation;
• SPDX/REUSE structure;
• privacy/data-minimization policy;
• trademark usage policy;
• brand asset quality checks.

Completion objective

Bring LibreCode to the same engineering and maintenance standard reached in LibreSign/brand, while preserving LibreCode's independent identity.

The final system must be reproducible, openly editable, accessible, reviewable, maintainable by humans, and straightforward for future contributors to update.

1. Repository architecture

Target structure:

• source/ — canonical editable inputs;
• guidelines/ — normative brand rules;
• manual/ — Typst manual;
• scripts/ — deterministic generation and quality checks;
• assets/ — generated-asset policy/build contract;
• docs/ — architecture, ADRs, references, registration facts, completion plan;
• LICENSES/ + REUSE.toml — precise licensing metadata.

Rules:

• there must be one canonical editable logo source;
• generated derivatives must not become parallel sources of truth;
• do not reintroduce a proprietary design file as a second canonical source;
• remove examples/ if it remains only a placeholder and normative examples live directly in the manual.

2. Canonical artwork and asset generation

Keep source/artwork/*-master.svg as the geometric source.

Generated SVG/PDF/PNG derivatives must come from scripts/build_assets.py + brand-assets.json.

Do not manually recreate generated assets.

Clear-space refactor

The current LibreCode implementation still calculates part of the clear-space construction inside Typst. Replace it with the proven architecture:

canonical SVG -> deterministic Python geometry -> generated technical SVG -> Typst composition only

The clear-space unit must be derived from LibreCode's own official artwork. Do not reuse LibreSign geometry or measurements.

3. Manual editorial completion

Review and complete the LibreCode manual with LibreCode-specific evidence for:

• how to use the manual and its scope;
• official name and pronunciation;
• meaning of LibreCode;
• purpose;
• primary/secondary audiences;
• positioning;
• concise messaging/brand promise if supported;
• practical free-software values;
• cooperative identity and contributor/community relationship;
• voice and tone;
• official artwork;
• approved variants/formats;
• composition;
• correct and incorrect use;
• logo colors;
• wider digital/interface palette only if actually approved;
• typography and intended weights;
• clear space;
• minimum size;
• partner/third-party use;
• accessibility;
• licensing;
• trademark;
• ownership;
• official sources.

Do not invent photography, illustration, motion, campaign templates, sub-brand systems, or other rules without approved source material.

Language

LibreCode may remain in Portuguese.

Use plain, direct Portuguese:

• prefer common words;
• use short sentences where practical;
• explain unavoidable specialist terms;
• avoid marketing clichés;
• avoid vague claims;
• distinguish project facts from legal promises.

4. Typst maintainability

Preserve:

• manual/main.typ = content;
• manual/components.typ = reusable layout functions;
• manual/theme.typ = brand tokens.

Required cleanup:

• remove unused/cross-brand LibreSign components or imports;
• replace positional TOC tuples such as entry.at(0) with named fields;
• use two-space indentation;
• use kebab-case for functions/variables;
• prefer set rules for defaults;
• use show rules only for structural transformation;
• keep normative source-derived geometry outside Typst;
• avoid unnecessary Typst package dependencies.

Formatter/lint workflow

Adopt Typstyle via the maintained typstyle-rs/typstyle-action.

• pin the Action to a full immutable commit SHA;
• keep the human-readable version as a comment;
• let Dependabot update the Action;
• use the same formatting baseline as LibreSign unless a LibreCode-specific reason requires otherwise.

Recommend Tinymist for editor diagnostics/linting.

Do not require Tinymist in CI unless it demonstrably catches useful issues beyond compiler + formatter.

Typst compiler

Keep an exact Typst compiler version in setup-typst.

Do not use latest or a floating range.

Compiler upgrades must be deliberate because they can change layout, pagination, PDF structure, accessibility tagging, or generated output.

Dependabot does not manage arbitrary with: typst-version values. That exact pin is intentional.

5. PDF accessibility and navigation

Reach the LibreSign baseline:

• PDF/UA-1 output;
• semantic document title;
• semantic headings;
• linked table of contents;
• bookmarks;
• TOC destinations landing at the top of section pages;
• alt text for meaningful images;
• decorative section numbers marked as PDF artifacts;
• correct Portuguese document language;
• selectable text;
• sensible reading order;
• independent veraPDF PDF/UA-1 validation in CI.

Automated validation does not replace human review.

Perform page-by-page visual review and subjective accessibility review before declaring completion.

6. CI, supply chain, and repository quality

Apply these conventions:

• pin every third-party GitHub Action to a full 40-character commit SHA;
• retain the version as a comment, e.g. # v6.0.0;
• make scripts/check_brand.py enforce immutable Action pins;
• add grouped weekly Dependabot for the github-actions ecosystem;
• rely on the installed DCO GitHub App instead of adding a competing custom DCO workflow;
• keep REUSE compliance;
• keep brand quality checks;
• keep manual/PDF validation checks.

When a maintained GitHub Action exists for a tool and Dependabot can manage it, prefer it over an arbitrary hardcoded download script unless reproducibility requires a standalone binary.

7. Licensing

The repository is intentionally multi-license.

Target model:

• documentation + official artwork: CC-BY-SA-4.0;
• scripts/automation: AGPL-3.0-or-later;
• fonts: upstream licenses;
• trademark rights: separate.

Required:

• keep SPDX per-file metadata;
• keep LICENSES/;
• keep REUSE compliance;
• add root LICENSE with the exact CC BY-SA 4.0 text so GitHub recognizes the primary repository license;
• make README explicitly explain that scripts and third-party fonts use different licenses.

8. Trademark and registration records

Issue #4 owns registration verification.

Separate:

• TRADEMARKS.md — usage policy;
• docs/registrations.md — factual public registration data.

Verify LibreCode data only from official INPI evidence.

Do not copy LibreSign registration facts.

Publish only useful public verification data. Exclude unnecessary administrative/payment identifiers and personal data.

If registration is verified and in force, a concise statement may appear in the manual; full details belong in docs/registrations.md.

9. README and repository presentation

README should:

• show the canonical LibreCode logo at the top where practical;
• describe this repository as the canonical brand system;
• link to the public guide;
• distinguish development/homologation output from stable releases;
• explain the multi-license model;
• state the open migration/source-of-truth boundary.

Do not add external status badges unless they accurately describe this repository.

10. Repository metadata

Issue #6 owns this step.

Apply and verify:

• canonical description;
• homepage;
• wiki disabled;
• delete merged branches enabled;
• relevant topics.

Do not close #6 until GitHub reports the expected values.

11. Release model

Use:

• latest = mutable development/homologation prerelease from main;
• vX.Y.Z = immutable approved release.

The current manual may be usable before v1.0.0.

Do not create v1.0.0 just because it builds or is usable.

Stable release gate:

• external homologation/review completed;
• accepted feedback incorporated;
• Verify and document trademark registrations #4 complete;
• Apply canonical repository metadata #6 complete;
• CI green;
• accessibility checks green;
• visual review complete;
• fresh release PR prepared from approved main;
• explicit approval to create the stable tag.

Execution order

Preferred order to minimize rework:

1. merge/land the durable completion plan from PR Record LibreCode brand completion plan from LibreSign lessons #8;
2. structural repository cleanup;
3. Typst cleanup + formatter + action pinning + Dependabot;
4. deterministic clear-space refactor;
5. PDF semantics/navigation/accessibility + veraPDF;
6. editorial expansion and brand-specific review;
7. README + root LICENSE + licensing clarification;
8. INPI registration verification (Verify and document trademark registrations #4);
9. repository metadata (Apply canonical repository metadata #6);
10. run full CI and inspect generated PDF;
11. publish/use mutable latest for homologation;
12. collect external review;
13. incorporate accepted feedback;
14. only then prepare first stable release.

Definition of done

The LibreCode brand system is complete for homologation when:

• PR Record LibreCode brand completion plan from LibreSign lessons #8 completion plan is merged;
• no unnecessary placeholder architecture remains;
• no cross-brand/dead Typst code remains;
• clear-space geometry is deterministic from canonical artwork;
• editorial scope is complete and LibreCode-specific;
• Typstyle gate passes;
• Actions are SHA pinned;
• Dependabot is configured;
• REUSE passes;
• brand quality checks pass;
• PDF builds as PDF/UA-1;
• veraPDF passes;
• navigation/bookmarks/alt text/artifacts are correct;
• visual/accessibility human review is complete;
• root LICENSE exists and multi-license scope is clear;
• trademark registration facts are verified/documented;
• repository metadata is applied;
• mutable latest works.

The first stable version is complete only after:

• external homologation is complete;
• accepted feedback is merged;
• explicit stable-release approval is given;
• versioned release workflow succeeds and artifacts/checksums are verified.

New-chat handoff

If this work is resumed in a fresh chat, give the assistant only:

https://github.com/LibreCodeCoop/brand

and instruct it to:

Read issue #1 first, then inspect #3, #4, #6, open pull requests, current main, and CI. Treat the repository as the source of truth and execute the remaining checklist in issue #1. Use LibreSign/brand only as the engineering-quality reference, not as a source of LibreCode-specific brand decisions. Do not create v1.0.0 until external homologation is explicitly complete.

That should be sufficient to reconstruct the intended work without relying on chat memory.

[vitormattos]

Progress update:

• Record LibreCode brand completion plan from LibreSign lessons #8 merged: the durable LibreSign-parity/completion plan is now on main.
• Harden LibreCode brand authoring and CI baseline #9 merged: removed placeholder/cross-brand Typst code, replaced positional TOC fields, documented Typstyle/Tinymist, pinned GitHub Actions by full SHA with version comments, added Dependabot, enforced action pins, and added Typstyle + veraPDF PDF/UA-1 gates.
• Generate LibreCode clear-space geometry outside Typst #11 merged: LibreCode clear-space geometry now follows canonical SVG -> deterministic Python geometry -> generated technical SVG -> Typst composition, while preserving the existing normative D/X rule.

All merged batches passed Brand quality, REUSE, manual build, and applicable asset/PDF validation checks.

Current work: #12 adds semantic headings, clickable TOC destinations, bookmarks, page-top section anchors, and PDF artifacts for decorative section numbers.

No stable release has been created.

[vitormattos]

Current handoff state after the completion pass:

• main: 347aada2c6cef901b0796377054c411822a3fd4f
• no open pull requests;
• Brand quality: green;
• REUSE: green;
• manual build: green;
• PDF/UA-1 + veraPDF: green;
• mutable latest: green and published as Latest homologation build;
• final PDF reviewed page by page; no clipping, overlap, broken glyphs, or layout regression found;
• GitHub recognizes the root license as CC-BY-SA-4.0.

All self-contained completion work is done. Two repository-definition-of-done items remain blocked on external input/permissions:

1. Verify and document trademark registrations #4 — official INPI evidence is still required to publish registration number, classes, status, and legal owner without guessing.
2. Apply canonical repository metadata #6 — repository metadata still needs an administrative write operation; the connected GitHub tooling can verify but cannot mutate those repository settings.

After those two items, the next phase is external homologation/review. No stable version has been created.

[vitormattos]

Homologation-ready state reached.

Additional completion:

• Document verified LibreCode INPI trademark registration #16 merged verified INPI registration facts from the official certificate into docs/registrations.md, TRADEMARKS.md, and the manual;
• Verify and document trademark registrations #4 is closed;
• Apply canonical repository metadata #6 is closed after live metadata verification;
• final manual build on 29b59f15e90d057f3ab0affba84452467f049942 passed Typstyle, asset generation, PDF/UA-1 compilation, veraPDF, Brand quality, REUSE, and mutable latest publication;
• the changed trademark/governance page was visually re-rendered and reviewed with no clipping/overflow;
• Document external homologation process #17 merged docs/external-homologation.md so external reviewers have a concrete scope, feedback format, and stable-release boundary.

There are no open pull requests. The only remaining work is inherently external: perform homologation/review, incorporate accepted feedback, then request explicit authorization before preparing/creating the first stable release.

[vitormattos]

Manual review correction merged in #18:

• README no longer exposes the temporary completion plan;
• user-facing manual prose no longer talks about repository paths, CI, Markdown filenames, or internal build mechanics;
• governance page was rewritten as brand guidance rather than repository governance;
• clear-space page was rebuilt from the LibreCode D module: the D in CODE is highlighted, four gray D references show the exclusion area, and top/bottom references are rotated while preserving X as the D width;
• a visual correct/incorrect-use page now includes rotated-logo and crowded-logo examples;
• clear-space generation now has unit tests executed by Brand quality.

The resulting PR PDF was rendered and visually checked on the affected pages before merge.