Sidebar Reorg Spec

archived Visibility internal Owner erik@uvilo.com Approver _ Created _ Updated _

Overview

This spec defines the ideal final information architecture for project landing pages, project hierarchy visibility, and readable access to non-Markdown files in the Uvilo OS site.

The goal is to preserve the existing sidebar hierarchy while making every project more navigable and making important project contents readable even when they are stored as non-Markdown files.

This spec describes the desired end state only. It does not describe implementation steps.

Problem

The current sidebar and content model make the site incomplete as a representation of the actual Uvilo OS repository.

Current issues include:

Many project directories do not have a clear landing page.
Non-Markdown files such as .ts, .json, .yaml, .py, .sh, and .txt are not readable in the site.
Users can understand a project’s conceptual docs, but cannot reliably inspect all files that belong to the project.
Some folders communicate meaning through structure alone, but that structure is not surfaced clearly to the reader.
Important project files may exist in the repository but remain absent from the visible navigation hierarchy.

The result is that parts of the real project are effectively hidden.

Design principles

The current sidebar hierarchy should remain in place.

This project is not intended to replace the existing menu structure with a single landing page per project.

Instead, the goal is to keep the existing hierarchy and make it more complete by adding project landing pages and adding readable navigation entries for files that are currently missing.

The primary unit of organization should still be the project.

A project is determined structurally from a maintained list of project holder folders.

A folder is a project folder if and only if it is exactly one level below a project holder folder.

Current project holder folders: Product/Projects, Forge/Projects, Forge/Skills

Product/Projects
Forge/Projects
Forge/Skills

Examples of project folders under the current rules include:

Product/Projects/Domain_Quiz/
Forge/Projects/Uvilo_OS/
Forge/Projects/OpenRouter/

Each project folder should have a single human-readable landing page.

Repository structure should remain meaningful

The site should reflect the existing folder structure rather than replacing it with a second categorization system.

If a folder is named Prompts, Schemas, Scripts, or Output, that naming already expresses the classification. The site should expose that structure directly.

README convention

Project landing pages should use the filename README.md.

This follows familiar repository conventions and clearly signals that the file is intended for human readers as the entry point to that project.

Auto-generated by default

Project README.md files should be auto-generated and kept up to date automatically.

Their purpose is to provide dependable project navigation and structure visibility.

If a better overview is desired for a specific project, that content may later be revised by an agent, but the default system should assume generation and freshness.

Human-readable, not implementation-facing

These pages are for human consumption. They should help a reader understand where they are, what the project contains, and how it relates structurally to surrounding projects.

Top-level principle

The sidebar should remain organized by major repository sections such as Architecture, Uvilo OS, Assistant, and the other top-level departments.

Project entry model

Every project folder should have a README.md page that is visible in the sidebar hierarchy.

Examples include:

Architecture/Domain_Quiz/README.md
Architecture/OpenRouter/README.md
Architecture/Uvilo_OS/README.md

These README.md pages are added to the project’s sidebar hierarchy. They do not replace the project’s existing visible files.

A project should continue to expose its files and subfolders through the existing visible hierarchy.

The improvement is that the hierarchy should become more complete:

project README.md pages become visible
supported non-Markdown files become visible through auto-generated readable file-view pages
image-containing folders become visible through generated MEDIA.md pages

The final system should make the existing navigation more complete, not collapse it into a single file per project.

README.md requirements for every project

Each project folder README.md should contain the following sections in this order.

1. Project title

The page should begin with the project title.

This should identify the project clearly and match the project’s role in the repository.

2. Overview

A short overview should explain what the project is.

The generator produces a default overview based on file counts and types. This overview is preserved on regeneration: if the overview text in an existing README differs from what the generator would produce, the existing text is kept.

The overview should remain brief and orient the reader, not attempt to replace the project’s actual spec or state documents.

3. Parent Project

This section should identify the nearest containing project folder above the current project, if one exists.

If no parent project exists, this section should be omitted.

This section is not auto-generated. It may be added manually to a README when the project hierarchy warrants it. Once present, it is preserved on regeneration.

4. Sub-projects

This section should list any nested project folders contained within the current project.

If no sub-projects exist, this section should be omitted.

This section is not auto-generated. It may be added manually to a README when the project hierarchy warrants it. Once present, it is preserved on regeneration.

5. Folder structure

This is the core of the README.

It should show the project’s folder structure with clickable links to all visible files.

The structure should reflect the actual directory hierarchy of that project.

If a file is directly renderable on the site, the link should open that page.

If a file is a supported non-Markdown text/code file, the link should open an auto-generated readable file-view page.

If a folder contains images, the folder structure should link to that folder’s generated MEDIA.md page.

The folder structure should be the main navigation feature of the README.

The README should follow this structure and add nothing else.

File visibility requirements

Goal

A reader should be able to navigate through the sidebar hierarchy and from a project README to every important readable file in that project.

This includes both Markdown and supported non-Markdown files.

Supported file viewing

Non-Markdown files that are text-based and meaningful for documentation should be viewable through the site by means of auto-generated file pages.

Examples include:

.ts
.tsx
.js
.jsx
.json
.yaml
.yml
.py
.sh
.sql
.txt
.css
.html

These files should not remain invisible simply because they are not Markdown.

SKILL.md exception

SKILL.md files use a skill-specific format that is incompatible with Starlight frontmatter. They are excluded from the Starlight content collection and instead treated as non-Markdown source files for file-view purposes.

The generator produces .view.md pages for SKILL.md files, rendering them as syntax-highlighted, read-only file-view pages rather than native Starlight content pages.

Auto-generated readable file-view page structure

Each supported non-Markdown file should have a single auto-generated readable file-view page.

Each file-view page should contain:

the file name as the page title
the full repository path to the file
the file type or extension
a link to the project README (labeled “Parent folder”)
a link to edit or view the source file in GitHub
the full file contents in a readable, syntax-highlighted code block when appropriate

If the file is too large to display reasonably in full, the file-view page may truncate the displayed contents, but it must still identify the source file clearly and provide a source link.

The page should make it clear that it is auto-generated from the source file.

Auto-generated readable file-view pages should be part of the project’s visible navigation hierarchy.

They exist to make currently hidden files visible and readable, not merely to create routes that remain absent from the sidebar.

Media folders

If a folder or sub-folder contains images, the system should generate a single MEDIA.md page for that folder instead of generating one readable page per image.

MEDIA.md should contain:

the folder name as the page title
the full repository path to the folder
a preview for each image in that folder
a download link for each image in that folder
links back to the parent folder location

This keeps image-heavy folders readable without flooding the site with one page per image.

Link behavior

Every clickable file entry in the folder structure should resolve to one of the following:

the original Markdown page, if the file is a Markdown page (excluding SKILL.md, which is rendered as a file-view page)
an auto-generated readable file-view page, if the file is a supported non-Markdown text/code file or a SKILL.md file
a generated MEDIA.md page, if the target is an image-containing folder represented that way

The project README should function as a dependable access point to the project’s complete readable contents.

Relationship rules

Parent project

A parent project is the nearest containing project folder above the current project, if such a project exists.

If no such project exists, the parent project section should be omitted.

Sub-projects

A sub-project is a nested project folder contained within the current project.

If no sub-projects exist, the sub-projects section should be omitted.

Structural only

Project relationships should be based on maintained project-holder and project-folder structure only.

The system should not infer conceptual similarity, historical connection, or team ownership as project relationships.

Scope of README generation

Required scope

Auto-generated README.md landing pages are required for project folders.

Not required for every nested folder

The ideal final state does not require every nested subfolder to have its own README.

Nested folders should be represented inside the project README’s folder structure unless they are themselves project folders under the maintained project-holder rules.

This keeps navigation aligned with the real project model.

Content philosophy

These pages should optimize for:

navigability
structural clarity
completeness of visible contents
consistency across projects
low maintenance burden

They should not optimize for:

editorial polish over freshness
manual curation of every project
duplicate explanations of folder meanings already expressed by the repository structure
subjective project relationship inference

Ideal final outcome

In the ideal final state:

A maintained list of project holder folders determines exactly which folders are project folders.