Skip to content
Uvilo OS
archived Visibility internal Owner erik@uvilo.com Approver _ Created _ Updated _

Sidebar Reorg Plan Implementation

Overview

This plan describes exactly how to implement the Sidebar Reorg spec in full. The goal is to preserve the existing sidebar hierarchy while making it more complete: every project gets a README.md landing page, non-Markdown source files become readable through auto-generated file-view pages, and image folders are represented through generated MEDIA.md pages. All new pages are added to the existing sidebar hierarchy alongside — not instead of — existing entries.

Reference documents:

Generation Strategy

Three categories of generated content, each with a different lifecycle:

CategoryLocationCommitted to GitRegenerated when
Project README.mdIn each project folder✅ YesAgent runs generator on demand after project changes
File-view pages.generated/Product/…/<file>.view.md❌ No (gitignored)Every Astro build
MEDIA.md pagesIn image-containing subfolders✅ YesAgent runs generator on demand

Why commit READMEs? READMEs are primary navigation documents. An agent may later customize the overview section. They are referenced by sidebar config (which is static). They should appear in the Git log as project history.

Why build-time for file-view pages? File-view pages are always derived from source files and never manually edited. Generating them during every Astro build keeps them perpetually fresh without polluting Git history. The .generated/ directory is gitignored; it exists only during the build and in local dev after running the generator.

Components

1. view_folder_config.json

Location: Forge/Projects/Sidebar_Reorg/view_folder_config.json

Defines the parameters that drive all generation:

{
  "project_holder_folders": ["Product/Projects", "Forge/Projects", "Forge/Skills"],
  "supported_extensions": [
    ".ts", ".tsx", ".js", ".jsx",
    ".json", ".yaml", ".yml",
    ".py", ".sh", ".sql",
    ".txt", ".csv", ".css", ".html"
  ],
  "image_extensions": [".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".ico"],
  "excluded_dirs": [
    ".git", "node_modules", ".internal"
  ],
  "generated_dir": ".generated"
}

Adding a new project holder folder in the future requires only a one-line change here and in .internal/src/content.config.ts.

2. generate_view_pages.ts

Location: Forge/Projects/Sidebar_Reorg/Scripts/generate_view_pages.ts

Single script with five responsibilities:

2a. Project scanner

  • Reads view_folder_config.json
  • For each project holder folder, lists all immediate subdirectories as project folders
  • Returns a list of ProjectFolder objects (path, name, parent project, sub-projects)

2b. README generator

Generates README.md in each project folder root.

README structure (as defined in the spec):

  1. YAML frontmatter (title, visibility, status, owner)
  2. Page title (# Project Name)
  3. Auto-generated overview paragraph (1–3 sentences describing the folder contents)
  4. ## Parent Project (omitted if none)
  5. ## Sub-projects (omitted if none)
  6. ## Folder Structure — clickable tree showing all visible files

Folder structure link rules:

  • .md file → links to its Starlight slug (e.g., /architecture/domain_quiz/domain_quiz_spec/)
  • Supported non-Markdown file → links to its file-view page slug (e.g., /architecture/domain_quiz/scripts/life-domain-quiz-qc.ts.view/)
  • Media-containing folder → links to its MEDIA.md slug (e.g., /architecture/domain_quiz/media/media/)
  • Empty folder or fully-excluded folder → listed without a link

Overview preservation: If a README.md already exists and contains the marker <!-- CUSTOM OVERVIEW START -->, the block between that marker and <!-- CUSTOM OVERVIEW END --> is preserved verbatim on regeneration. All other sections are always overwritten.

2c. File-view page generator

For each supported non-Markdown file found under a project folder tree (excluding excluded_dirs), generates a Markdown page at:

.generated/Architecture/<ProjectFolder>/<path>/<filename>.<ext>.view.md

Example:

  • Source: Product/Projects/Domain_Quiz/Scripts/life-domain-quiz-qc.ts
  • Generated: .generated/Product/Projects/Domain_Quiz/Scripts/life-domain-quiz-qc.ts.view.md

Each file-view page contains:

---
title: "life-domain-quiz-qc.ts"
generated: true
---

# life-domain-quiz-qc.ts

| Field | Value |
|---|---|
| **Type** | TypeScript |
| **Path** | `Product/Projects/Domain_Quiz/Scripts/life-domain-quiz-qc.ts` |
| **Parent folder** | [Domain Quiz](../../../product/projects/domain_quiz/readme/) |

[View source on GitHub](https://github.com/ErikDakoda/uvilo-os/blob/dev/Product/Projects/Domain_Quiz/Scripts/life-domain-quiz-qc.ts)

> This page is auto-generated from the source file. Edit the source to change the content.

```typescript
<file contents>
\```

If the file exceeds 500 lines, show the first 500 lines followed by a note and the source link.

2d. MEDIA.md generator

For each project subfolder containing at least one media file:

  • Generates MEDIA.md in that subfolder
  • Content: folder title, path breadcrumb, one section per media file with:
    • Media preview (Markdown ![]() for images)
    • Filename, dimensions if detectable
    • Download link (GitHub raw URL)

MEDIA.md is treated as a regular file in the sidebar — it appears alongside .md files and file-view pages within the same folder group, not as a separate sidebar entry.

Media folders are committed (like READMEs).

2e. Sidebar snippet generator

Outputs a complete updated sidebar group for each Product project, formatted as valid JavaScript for the agent to review and paste into astro.config.mjs.

The generator does NOT parse astro.config.mjs directly (brittle). Instead it outputs a .generated/sidebar-additions.md report listing, per project:

  • The README slug to add at the top of that project’s items array
  • The file-view page slugs to add (with suggested placement)
  • The MEDIA.md slugs to add alongside other .md files in the same folder

MEDIA.md files are treated as regular content files — they appear in the sidebar alongside .md files and file-view pages for the same folder, not as a separate special entry.

The agent reads this report and manually applies the additions to astro.config.mjs, preserving all existing entries and nested groups.

Example: Domain Quiz before and after:

// Before
{ slug: 'architecture/domain_quiz/domain_quiz_spec' },
// Prompts group...

// After — README added at top; file-view slugs added for Scripts and Schemas
{ slug: 'architecture/domain_quiz/readme' },
{ slug: 'architecture/domain_quiz/domain_quiz_spec' },
{
  label: 'Prompts', collapsed: true, items: [
    { slug: 'architecture/domain_quiz/prompts/analyze_life_domain_quiz_prompt' },
  ],
},
{
  label: 'Scripts', collapsed: true, items: [
    { slug: 'architecture/domain_quiz/scripts/life-domain-quiz-qc.ts.view' },
  ],
},
{
  label: 'Schemas', collapsed: true, items: [
    { slug: 'architecture/domain_quiz/schemas/analyzelifedomainquizschema.ts.view' },
    { slug: 'architecture/domain_quiz/schemas/uploadquizschema.ts.view' },
  ],
},

The existing sidebar entries are always preserved. New entries are additions only.

3. Content config update (content.config.ts)

Two changes needed:

Add .generated/ glob pattern:

'.generated/Architecture/**/*.md',

Update generateId to strip the .generated/ prefix so slugs are clean:

generateId: ({ entry }) => {
  return entry
    .replace(/^\.generated\//, '')
    .replace(/\.mdx?$/, '')
    .toLowerCase();
},

This makes .generated/Architecture/Domain_Quiz/Scripts/life-domain-quiz-qc.ts.view.md resolve to slug architecture/domain_quiz/scripts/life-domain-quiz-qc.ts.view, which maps to URL /architecture/domain_quiz/scripts/life-domain-quiz-qc.ts.view/.

4. Package.json build/dev scripts

.internal/package.json is updated to run the generator before every Astro build.

The script is executed with tsx, a zero-config TypeScript runner. Add it as a dev dependency:

npm install --save-dev tsx

Then update the scripts:

"generate": "tsx ../Architecture/Sidebar_Reorg/Scripts/generate_view_pages.ts",
"dev":      "npm run generate && astro dev",
"build":    "npm run generate && astro check && astro build",

tsx runs TypeScript directly without a separate compilation step, using the existing tsconfig.json in .internal/. No build output is produced — the script is executed once at dev/build time and discarded.

Running npm run generate locally before astro dev ensures file-view pages are present for the dev server. Running it as part of build ensures Vercel always has fresh pages.

5. .gitignore update

Add to the repo root .gitignore:

# Generated file-view pages (rebuilt during every Astro build)
.generated/

READMEs and MEDIA.md files are committed normally and are NOT excluded.

Current Project Inventory

All 15 immediate subfolders of Architecture/ are project folders. The table below summarizes what generation is needed for each:

ProjectREADME neededNon-Markdown filesImage folders
Analytics✅None foundNone found
Analyze_Convo✅None foundNone found
Domain_Quiz✅Scripts/.ts, Schemas/.tsNone found
Goodreads✅.html,.csv × manyNone found
Libre_Agents✅None foundNone found
Life_Circumstances✅*.csv × 2None found
Life_Domains✅None foundNone found
Onboarding_Quiz✅None foundNone found
OpenRouter✅None foundNone found
Persistent_Memory✅None foundNone found
Sidebar_ReorgAlready existsNone foundNone found
Taxonomy✅Scripts/taxonomy_qc.tsNone found
Uvilo_Method✅None foundNone found
Uvilo_OS✅None foundNone found
Bash_Refactor✅None foundNone found

The generator script will perform a full scan at runtime and handle any files not captured in this table.

Phases

Phase 1 — Infrastructure Setup

Build the generator script and configuration; update the Astro content pipeline. Nothing is visible to site users yet.

Tasks:

  • Create Architecture/Sidebar_Reorg/view_folder_config.json
  • Install tsx as a dev dependency in .internal/
  • Implement project scanner module in generate_view_pages.ts
  • Implement README generator module (overview, folder structure, parent/sub-project sections)
  • Implement file-view page generator module
  • Implement MEDIA.md generator module
  • Implement sidebar snippet generator module
  • Update content.config.ts — add .generated/ glob and update generateId
  • Update .internal/package.json — add tsx dev dep, add generate, update dev and build scripts
  • Add .generated/ to repo root .gitignore
  • Add generator script and config to sidebar in astro.config.mjs

Verification: Run npm run generate locally; confirm .generated/ is created with the correct file-view pages. Run npm run dev; confirm file-view pages are accessible.

Phase 2 — README Generation (First Run)

Generate and commit README.md for all 14 Architecture projects that currently lack one, and add each README slug to the top of its project’s existing sidebar group.

Tasks:

  • Run generator: npm run generate
  • Review generated READMEs — spot check folder structure links and overview text
  • Manually adjust any auto-generated overview text that is misleading or empty
  • Read .generated/sidebar-additions.md — apply README slug additions to the top of each project’s existing items array in astro.config.mjs (preserve all existing entries)
  • Commit all new README.md files and the updated astro.config.mjs

Verification: Deploy to Vercel preview; confirm all project READMEs are accessible from the sidebar, existing entries are still present, and folder structure links resolve.

Phase 3 — Non-Markdown File Visibility

Generate file-view pages for all supported non-Markdown files, add their slugs to the sidebar, and confirm they are reachable from both the sidebar and their project READMEs.

Tasks:

  • Run npm run build locally and confirm .generated/ is populated with file-view pages
  • Spot-check file-view pages for Domain_Quiz .ts files, Goodreads .html/.csv files, and Taxonomy .ts file
  • Confirm syntax highlighting renders correctly in Starlight
  • Confirm that each project README’s folder structure links to the correct file-view slugs
  • Handle large files: verify the 500-line truncation rule works for Goodreads .csv/.html
  • Read .generated/sidebar-additions.md — apply file-view page slug additions to each project’s sidebar group in astro.config.mjs, grouped by subfolder where appropriate (e.g. a Scripts sub-group for architecture/domain_quiz/scripts/…)
  • Commit updated astro.config.mjs

Verification: Navigate both the sidebar AND project READMEs in preview; confirm file-view links in both routes resolve; content is readable; GitHub source link is correct.

Phase 4 — Media Folder Pages

Generate MEDIA.md pages for any media-containing folders. MEDIA.md files are listed in the sidebar alongside other .md files in the same folder.

Tasks:

  • Run full directory scan across all Architecture projects to find media files
  • If media folders are found: generate MEDIA.md, review previews, commit
  • If no media folders are found: mark this phase N/A and note in State doc

Verification: If applicable, confirm MEDIA.md pages render media previews and download links in the preview deployment. Confirm MEDIA.md appears in the sidebar alongside sibling .md files.

Phase 5 — Sidebar Completeness Review

Verify that the sidebar is now a complete and accurate representation of all project contents. Nothing is removed; this phase is a review and gap-fill pass.

Tasks:

  • Confirm all 15 Architecture project groups have a { slug: '…/readme' } entry at the top
  • Confirm all file-view page slugs from Phase 3 are present in the sidebar
  • Confirm all MEDIA.md slugs from Phase 4 (if any) are present in the sidebar
  • Identify any remaining non-Markdown files that were missed and add their file-view slugs
  • Decide whether architecture/architecture (the Architecture overview page) should link to all project READMEs — update if yes
  • Commit final astro.config.mjs

Verification: Full manual walk-through of the Architecture section in the preview site. Every project is reachable via sidebar and README. No broken links. No hidden files remain.

Phase 6 — Build Integration & Final Verification

Confirm the generator is correctly integrated into the Vercel build pipeline and the production site reflects all changes.

Tasks:

  • Verify Vercel project build command invokes npm run build (which now includes npm run generate)
  • Trigger a full Vercel preview deployment and confirm .generated/ file-view pages are present and accessible
  • Confirm astro check passes (no type errors from new content)
  • Confirm starlightAutoSidebar plugin does not conflict with the new sidebar structure
  • Full end-to-end test: pick one project (Domain_Quiz), navigate from sidebar → README → file-view page → GitHub source link
  • Merge to dev and confirm production deployment at os.uvilo.com

Verification: All above steps pass. No 404s. No build warnings from generated content.

Technical Decisions Log

DecisionChoiceRationale
README lifecycleGenerated + committedPrimary docs; may be agent-customized; transparent in Git
File-view page lifecycleGenerated at build time; gitignoredAlways derived from source; no manual editing; keeps Git clean
MEDIA.md lifecycleGenerated + committedTreated as project docs, like README
File-view page location.generated/Architecture/…/<file>.<ext>.view.mdMirrors source path; clean slug after prefix strip
Overview preservationMarker-based (<!-- CUSTOM OVERVIEW START/END -->)Allows agent customization without losing auto-generated sections
Sidebar per-project entryREADME added to top of existing group; file-view and MEDIA.md slugs added alongsideExisting hierarchy preserved; sidebar becomes more complete, not collapsed
Generator languageTypeScriptConsistent with codebase language; runs via tsx (zero-config); type-safe path/fs operations
Truncation threshold500 linesBalances readability with page weight; exact value configurable

Files Created or Modified by This Project

New files (this plan)

  • Architecture/Sidebar_Reorg/Sidebar_Reorg_Plan_Implementation.md — this file

New files (implementation)

  • Architecture/Sidebar_Reorg/view_folder_config.json
  • Architecture/Sidebar_Reorg/Scripts/generate_view_pages.ts
  • Architecture/<each project>/README.md × 14 (generated, committed)
  • <media folder>/MEDIA.md × TBD (generated, committed)
  • .generated/Architecture/…/*.view.md × many (generated, gitignored)

Modified files (implementation)

  • .internal/src/content.config.ts — add .generated/ glob and updated generateId
  • .internal/package.json — add generate script, update dev and build
  • .internal/astro.config.mjs — add Plan to sidebar; Phase 2 README slugs added; Phase 3 file-view slugs added; Phase 4 MEDIA.md slugs added (if applicable)
  • .gitignore (repo root) — add .generated/