feat: add AGENTS.md and CLAUDE.md for project documentation; update README with features and installation instructions; modify index.html and manifest for consistent naming; enhance App component with new cartridge tools

2026-04-14 18:48:31 -04:00 · 2026-04-14 18:48:31 -04:00 · 686f0795d0
commit 686f0795d0
parent 87550fe5ee
6 changed files with 169 additions and 8 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,95 @@
+# Meatloaf Manipulator — Agent Context
+
+## Project Overview
+
+**Meatloaf Manipulator** is a React/Vite PWA for configuring and managing Meatloaf devices (Commodore 64 retro computing hardware). It is served at `https://meatloaf.cc/config/`.
+
+## Tech Stack
+
+- **Framework**: React 18 + Vite 6
+- **Styling**: Tailwind CSS 4 (via `@tailwindcss/vite`)
+- **UI components**: Radix UI primitives, MUI icons (`@mui/icons-material`), Lucide React icons
+- **Routing**: React Router 7 (single-page, page state managed in `App.tsx`)
+- **Build base path**: `/config/` (overridable via `BASE_PATH` env var)
+
+## Project Structure
+
+```
+src/
+  app/
+    App.tsx               # Root component: routing, nav, layout
+    components/
+      StatusPage.tsx       # System status, activity log, file info, progress, overlays
+      DevicesPage.tsx      # Device list
+      DeviceDetailOverlay.tsx
+      GeneralPage.tsx      # General/settings
+      IECPage.tsx          # IEC bus configuration
+      NetworkPage.tsx      # Network settings
+      OtherPage.tsx        # Misc settings
+      ToolsPage.tsx        # Tools
+      SearchOverlay.tsx
+      WiFiScanOverlay.tsx
+      FileBrowser.tsx
+      figma/               # Figma-generated components
+      ui/                  # shadcn/Radix UI wrappers
+  imports/
+    logo.svg
+    config.json            # Device config data shape
+  main.tsx
+  styles/
+public/
+  manifest.webmanifest
+  icon.192.png / icon.512.png
+  service-worker.js        # PWA service worker
+index.html
+vite.config.ts
+```
+
+## Navigation
+
+Bottom tab bar + header icons:
+
+| Nav item    | Page key    | Component        |
+|-------------|-------------|------------------|
+| Status      | `status`    | StatusPage       |
+| Devices     | `devices`   | DevicesPage      |
+| IEC         | `iec`       | IECPage          |
+| Network     | `network`   | NetworkPage      |
+| More        | `other`     | OtherPage        |
+| (header)    | `apps`      | Apps grid        |
+| (profile)   | `general`   | GeneralPage      |
+| (profile)   | `tools`     | ToolsPage        |
+
+## Apps Page
+
+Grid of app cards grouped by category, each navigates to a stub `AppPage`:
+
+- **Disk**: Directory Editor, Sector Editor, BAM Editor, Disk Visualizer, RAM/ROM Explorer, Dump Disk Image, Write Disk Image
+- **Cartridge**: PRG to CRT, Magic Desk Cart Builder, Easy Flash Cart Builder
+- **Development**: Basic Editor, Assembler, Sprite Editor, Character Set Editor, Petscii Editor
+- **Display**: Idle Animation, Loading Animation
+
+All individual app pages are currently stubs (`AppPage` component with "coming soon" message).
+
+## Work to Date (chronological)
+
+1. **Initial commit** — project scaffolded with basic pages
+2. **StatusPage enhancements** — file info display, loading progress bar
+3. **StatusPage overlays** — reset functionality, directory map overlay, disk map overlay
+4. **SearchOverlay polish** — improved layout, responsiveness, background opacity
+5. **DeviceDetailOverlay** — media button titles improved
+6. **Apps page** — added `apps` nav item; built `AppCard` grid with category groupings; added stub `AppPage` for all individual apps
+7. **StatusPage layout** — reorganized action buttons; enhanced system status display and activity log
+8. **PWA support** — added `manifest.webmanifest`, service worker, PWA icons (`icon.192.png`, `icon.512.png`)
+9. **Vite base path** — set `base: process.env.BASE_PATH || '/config/'` in `vite.config.ts`
+10. **Icon/manifest path fix** — updated icon paths in manifest and HTML; adjusted service worker registration
+
+## Known Issues / Open Work
+
+- **Service worker 404**: `https://meatloaf.cc/service-worker.js` returns 404. The SW is likely not being copied to the dist output at the correct path, or the registration URL does not account for the `/config/` base path.
+- **App pages**: All individual app pages (Directory Editor, Sector Editor, etc.) are stubs. Actual implementations are pending.
+- **`apple-mobile-web-app-capable` deprecation**: Already resolved in `index.html` (uses `mobile-web-app-capable` instead).
+
+## Configuration Shape
+
+Config is loaded from `src/imports/config.json` and passed as props (`config`, `setConfig`) to all page components.
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,3 @@
+# Claude Code — Meatloaf Manipulator
+
+@AGENTS.md
--- a/README.md
+++ b/README.md
@ -1,11 +1,59 @@

-  # Settings Management Interface
+# Meatloaf Manipulator

-  This is a code bundle for Settings Management Interface. The original project is available at https://www.figma.com/design/5Ki7UngcQtfQS3uZtSBHP1/Settings-Management-Interface.
+A Progressive Web App (PWA) for configuring and managing [Meatloaf](https://meatloaf.cc) devices — open-source Commodore 64/128 hardware that adds modern networking, storage, and peripheral support.

-  ## Running the code
+## Features

-  Run `npm i` to install the dependencies.
+- **Status** — live system status, activity log, file info, loading progress, directory and disk map overlays
+- **Devices** — browse and manage attached storage devices with detailed device overlays
+- **IEC** — configure the IEC serial bus
+- **Network** — manage network settings and scan for Wi-Fi networks
+- **Apps** — built-in tools grouped by category:
+  - **Disk**: Directory Editor, Sector Editor, BAM Editor, Disk Visualizer, RAM/ROM Explorer, Dump/Write Disk Image
+  - **Cartridge**: PRG to CRT, Magic Desk Cart Builder, Easy Flash Cart Builder
+  - **Development**: Basic Editor, Assembler, Sprite Editor, Character Set Editor, PETSCII Editor
+  - **Display**: Idle Animation, Loading Animation
+- **Tools & Settings** — general configuration and utility tools
+- **PWA** — installable on desktop and mobile; runs offline via service worker

-  Run `npm run dev` to start the development server.
+## Requirements

+- Node.js 18+
+- npm or pnpm
+
+## Installation
+
+```bash
+npm install
+# or
+pnpm install
+```
+
+## Development
+
+```bash
+npm run dev
+```
+
+The app is served at `http://localhost:5173/config/` by default.
+
+To use a different base path:
+
+```bash
+BASE_PATH=/my-path/ npm run dev
+```
+
+## Production Build
+
+```bash
+npm run build
+```
+
+Output is written to `dist/`. The build uses `/config/` as the base path by default. Override with the `BASE_PATH` environment variable at build time:
+
+```bash
+BASE_PATH=/config/ npm run build
+```
+
+Deploy the contents of `dist/` to the Meatloaf device web server under the configured base path.
--- a/index.html
+++ b/index.html
@ -4,7 +4,7 @@
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-      <title>Meatloaf Config</title>
+      <title>Meatloaf Manipulator</title>
      <meta name="theme-color" content="#4d4d4d" />
      <link rel="manifest" href="/manifest.webmanifest" />
      <link rel="icon" type="image/png" sizes="192x192" href="/icon-192.png" />
--- a/public/manifest.webmanifest
+++ b/public/manifest.webmanifest
@ -1,5 +1,5 @@
 {
-  "name": "Meatloaf Config",
+  "name": "Meatloaf Manipulator",
  "short_name": "Meatloaf",
  "start_url": ".",
  "display": "standalone",
--- a/src/app/App.tsx
+++ b/src/app/App.tsx
@ -22,6 +22,9 @@ type AppId =
  | 'ramrom-explorer'
  | 'dump-disk-image'
  | 'write-disk-image'
+  | 'prg-to-crt'
+  | 'magic-desk-cart-builder'
+  | 'easy-flash-cart-builder'
  | 'basic-editor'
  | 'assembler'
  | 'sprite-editor'
@ -61,6 +64,15 @@ export default function App() {
              <AppCard icon={<Upload className="w-7 h-7" />} label="Write Disk Image" onClick={() => setCurrentPage('write-disk-image')} />
            </div>
          </div>
+          {/* Cartridge Group */}
+          <div>
+            <h2 className="text-lg font-semibold mb-4 text-blue-700">Cartridge</h2>
+            <div className="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 gap-4">
+              <AppCard icon={<Folder className="w-7 h-7" />} label="PRG to CRT" onClick={() => setCurrentPage('prg-to-crt')} />
+              <AppCard icon={<Edit className="w-7 h-7" />} label="Magic Desk Cart Builder" onClick={() => setCurrentPage('magic-desk-cart-builder')} />
+              <AppCard icon={<LayoutList className="w-7 h-7" />} label="Easy Flash Cart Builder" onClick={() => setCurrentPage('easy-flash-cart-builder')} />
+            </div>
+          </div>
          {/* Development Group */}
          <div>
            <h2 className="text-lg font-semibold mb-4 text-green-700">Development</h2>
@ -91,6 +103,9 @@ export default function App() {
    'ramrom-explorer': <AppPage title="RAM/ROM Explorer" onBack={() => setCurrentPage('apps')} />, 
    'dump-disk-image': <AppPage title="Dump Disk Image" onBack={() => setCurrentPage('apps')} />, 
    'write-disk-image': <AppPage title="Write Disk Image" onBack={() => setCurrentPage('apps')} />, 
+    'prg-to-crt': <AppPage title="PRG to CRT" onBack={() => setCurrentPage('apps')} />, 
+    'magic-desk-cart-builder': <AppPage title="Magic Desk Cart Builder" onBack={() => setCurrentPage('apps')} />, 
+    'easy-flash-cart-builder': <AppPage title="Easy Flash Cart Builder" onBack={() => setCurrentPage('apps')} />,
    'basic-editor': <AppPage title="Basic Editor" onBack={() => setCurrentPage('apps')} />, 
    'assembler': <AppPage title="Assembler" onBack={() => setCurrentPage('apps')} />, 
    'sprite-editor': <AppPage title="Sprite Editor" onBack={() => setCurrentPage('apps')} />,