Refactor branding assets and rewrite the codebase README

[kauevestena]

Objective

Create a dedicated branding area under assets/, move the current OSWM identity files into it, update every reference to the moved files, centralize branding-path configuration, and rewrite the repository README so it accurately documents the current architecture and development workflow.

Branch and PR

• Create a branch named agent/refactor-branding-and-readme from main.
• Do not merge.
• Open a draft pull request against main.
• Keep the branding refactor and README rewrite in the same PR because the README must document the resulting structure.

Branding inventory to move

The following files must be included:

• assets/favicon_homepage.png
• assets/page_logo.png
• assets/page_logo_clean.png
• assets/page_logo_dark_clean.png
• assets/homepage/project_logo.png
• assets/homepage/project_logo_100px.png
• every banner file under assets/ or assets/homepage/ whose filename ends in _clean before the extension

Before moving anything, list all matching banner filenames in the PR description so the inventory is explicit and reviewable.

Target structure

Use this structure unless an existing convention in the repository clearly requires a small adjustment:

assets/
  branding/
    favicon_homepage.png
    manifest.json
    logos/
      page_logo.png
      page_logo_clean.png
      page_logo_dark_clean.png
      project_logo.png
      project_logo_100px.png
    banners/
      <all *_clean banner files>

Do not move unrelated homepage illustrations, map symbols, styles, generated legends, or deprecated assets.

Centralized branding manifest

Introduce assets/branding/manifest.json as the canonical registry of shared branding resources. Its purpose is to prevent branding filenames and paths from being duplicated throughout Python, HTML, JavaScript, CSS, templates, and generated outputs.

A reasonable initial schema is:

{
  "favicon": "assets/branding/favicon_homepage.png",
  "logos": {
    "page": "assets/branding/logos/page_logo.png",
    "page_clean": "assets/branding/logos/page_logo_clean.png",
    "page_dark_clean": "assets/branding/logos/page_logo_dark_clean.png",
    "project": "assets/branding/logos/project_logo.png",
    "project_100px": "assets/branding/logos/project_logo_100px.png"
  },
  "banners": {
    "<semantic_name>": "assets/branding/banners/<filename>"
  }
}

The agent may refine the schema after inspecting how assets are consumed, but must preserve these principles:

• one authoritative registry for shared branding paths;
• semantic keys rather than consumers depending directly on filenames;
• no environment-specific absolute URLs;
• paths must remain valid when this repository is mounted as the oswm_codebase submodule of a node;
• browser-only code must receive the manifest through a static-compatible mechanism, with no server dependency;
• avoid adding a second Python-only registry that can drift from the JSON manifest;
• document the manifest contract in the README.

Where direct manifest consumption would make a static page unnecessarily complex, generators may resolve semantic keys while building the page. The generated output may contain final asset URLs, but source templates and generators should not duplicate legacy paths.

Refactoring requirements

1. Use git mv so history remains traceable.
2. Search the entire repository for references to every moved filename.
3. Update Python, HTML, JavaScript, CSS, Markdown, templates, tests, generated-page sources, and documentation references.
4. Pay particular attention to known references in:
   • webmap/webmap_base.html
   • webmap/snapshot/snapshot_composer.js
   • routing/routing_demo.html
   • modules_info.py
   • data-quality page generators
   • dashboard generators
   • homepage generation code
5. Replace scattered hardcoded branding paths with semantic lookups from the manifest wherever practical.
6. Do not manually edit large generated outputs unless the repository workflow requires generated files to remain committed. Prefer changing their generator and regenerating them.
7. Preserve relative-link behavior for node repositories that consume oswm_codebase as a submodule.
8. After the move, no active code path may reference the previous locations.
9. References inside genuinely deprecated snapshots may either be updated or explicitly documented as intentionally frozen; active code must be clean.
10. Do not create needless abstraction around non-branding assets; the manifest is specifically for stable shared identity resources.
11. Add a lightweight validation test or script that checks that every manifest entry exists and that no duplicate semantic key maps unintentionally to a missing file.

README rewrite

Replace the current minimal README with an up-to-date project README in English. It should include at least:

1. Project overview

   • Explain OpenSidewalkMap (OSWM) as a decentralized, modular, GitHub-hosted ecosystem for pedestrian-network inventory, visualization, analysis, routing, data quality, monitoring, and distribution using primarily OpenStreetMap data.

2. Role of this repository

   • Explain that oswm_codebase is the shared codebase used as a Git submodule by individual OSWM node repositories.
   • Distinguish shared source code/assets from node-specific configuration, generated data, and published outputs.

3. Architecture

   • Describe the relationship between:
     • the project-level repository/organization;
     • this shared codebase;
     • node repositories such as kauevestena/opensidewalkmap_beta;
     • generated GitHub Pages outputs.
   • Add a compact directory tree covering the important top-level modules.

4. Current modules

   • Webmap and scrutiny snapshots
   • Dashboard/statistics
   • Data quality and completeness
   • Routing demo
   • Data hub/API-related outputs
   • Change monitoring/RSS where currently present
   • Clearly label prototypes or deprecated components as such.

5. Branding assets

   • Document assets/branding/ and the purposes of its favicon, page logos, project logos, dark-theme variant, clean banners, and manifest.json.
   • Explain semantic manifest keys and how generators/static pages resolve them.
   • State that shared branding paths must remain compatible with node repositories using this repository as oswm_codebase.

6. Local development

   • Replace the current one-line use local_setup.sh instruction with actual prerequisites and setup steps based on the repository files.
   • Explain submodule-aware development where relevant.
   • Include representative commands, but do not invent dependencies that are not supported by repository configuration.

7. Testing and validation

   • Document available automated tests and useful smoke checks.
   • Explain how to serve a node locally to verify relative paths and static resources.
   • Document the branding-manifest integrity check.

8. Creating or updating a node

   • Briefly explain that nodes consume the codebase as a submodule and point to the node-template/model README.

9. Repository links and contribution notes

   • Retain valid project links.
   • Add concise contribution guidance and clarify that generated files should normally be changed through their generators.

Remove obsolete wording, placeholders, and claims that no longer match the repository.

Coordinated node-template README update

The codebase PR must also prepare the documentation contract for the node-template/model repository, currently represented by kauevestena/opensidewalkmap_beta.

Because the node README lives in another repository, implement this as a coordinated second branch and draft PR rather than modifying it from the codebase branch:

• repository: kauevestena/opensidewalkmap_beta;
• branch: agent/update-node-readme;
• do not merge;
• open a draft PR against main;
• link both draft PRs to each other and to this issue.

Rewrite the node README in English and include:

1. what an OSWM node is and how decentralized node repositories relate to the shared codebase;
2. prerequisites and recursive clone/submodule initialization commands;
3. how to initialize, update, inspect, and deliberately pin the oswm_codebase submodule;
4. which files are node-specific configuration versus generated outputs;
5. the current modules exposed by a node, based on the actual repository rather than the obsolete four-module list;
6. local generation and local static-server instructions;
7. GitHub Pages publication workflow, based only on existing repository automation;
8. how branding is inherited from oswm_codebase/assets/branding/manifest.json and which aspects, if any, are node-configurable;
9. how to upgrade a node after a codebase branding-path change;
10. troubleshooting for missing submodules, stale submodule pointers, broken relative asset URLs, and generated files that are out of date;
11. removal of TODO placeholders such as automatic README generation unless an actual tracked implementation exists.

The node README must not claim that opensidewalkmap_beta is itself the universal template unless the repository metadata and workflow support that claim. Use wording such as “reference node” or “node model” where more accurate.

Validation

Run and report:

• a repository-wide search proving that active references to old branding paths are gone;
• a search showing that source files no longer scatter direct paths for manifest-managed assets, except justified generated output or documented compatibility cases;
• validation that all manifest paths exist;
• available unit or integration tests;
• a static/local-server smoke test of the homepage, webmap, routing page, snapshot composer, dashboard entry point, and data-quality entry point;
• checks that both normal and dark-theme logos load;
• checks that every moved banner and favicon returns successfully;
• git diff --check.

Also test the change from a real node checkout with the submodule path named oswm_codebase, because passing tests inside this repository alone is insufficient.

For the coordinated node PR, also verify:

• recursive clone instructions work in a clean checkout;
• the documented submodule-update commands match the actual .gitmodules configuration;
• all README links resolve;
• the node can load the new branding paths through a local static server.

Acceptance criteria

• All specified identity files and all matching clean banners are under assets/branding/.
• No unrelated assets are moved.
• assets/branding/manifest.json is the documented canonical branding registry.
• Active source references use semantic manifest resolution where practical rather than scattered hardcoded paths.
• Active references resolve correctly from a consuming node repository.
• The dark-theme logo is used where the UI requires it and remains documented.
• The codebase README reflects the current project and repository architecture.
• A coordinated draft PR updates the node/reference-model README and links back to the codebase PR.
• Both draft PR descriptions contain validation results and cross-links.
• The codebase draft PR contains the complete asset inventory and any intentionally retained deprecated references.
• Nothing is merged.