# Agent Notes

## Project Overview

The HyperCard Center is a small PHP website that publishes HyperCard/HyperTalk documentation in a web-friendly form. The public site name is "The HyperCard Center" and the main content currently centers on the HyperTalk Reference stack, with both "modern" and "retro" renderings.

## Architecture

- `web/index.php` is the front controller. It sets error handling/logging, includes `code/cw_include.inc.php`, derives `$PATH` from the request URI, and returns `cw_route()`.
- `code/cw_include.inc.php` wires dependencies and local includes, then creates `$SITE['db']` as a lazy `CWDatabase` wrapper.
- `code/site.inc.php` contains environment/site configuration. Local development is detected by `/Users/charles/dev` or `/home/charles/dev`; otherwise it assumes production.
- `code/route.inc.php` handles all routing, view-mode cookies, hit logging under `cache/`, stack/card redirects, and `/do/*` JSON endpoints.
- `code/layout.inc.php` renders the shared HTML shell plus modern/retro page chrome.
- `pages/*.php` are the routed page bodies. `pages/HyperTalkReference-index.php` and `pages/HyperTalkReference-read.php` are the main stack views.
- `code/functions.inc.php` contains legacy/shared formatting, API, SSO, and helper functions.
- `code/cw_database.inc.php` is a simple lazy PDO/MySQL helper. The current public pages mostly read files, but the DB object is still constructed on boot.

## Content And Data

- `data/HyperTalkReference-topics.json` is the runtime topic/card index used by the HyperTalk Reference routes.
- `pages/HyperTalkReference-read.php` reads runtime card Markdown from `store/HyperTalkReference/{section}/{card}.md` and placeholder Markdown from `store/HelpExtras/Placeholders/{name}.md`.
- `store/` is a separate nested Git repository containing the published Markdown content. From the parent repo it may appear as untracked `store/`; check status inside `store/` before editing or committing content there.
- `store/HelpExtras/` contains Glossary, Placeholders, Tips, and Troubleshooting Markdown. `store/HyperTalkReference/` contains section folders such as `commands`, `functions`, `keywords`, and `properties`.
- This checkout also has source/generated files under `mds/` and `scripts/`; treat those as conversion/source artifacts rather than the live content read by the current pages unless a task specifically concerns regeneration.
- Current regeneration flow starts from `scripts/HyperTalk Reference.json` and `scripts/Help Extras.json`, which are JSON exports of the original stacks.
- HyperTalk Reference generation:
  - `scripts/topics-htr.php` reads `scripts/topics.json` and writes `data/HyperTalkReference-topics.json`.
  - `scripts/new-ref-proc.php` and older `scripts/ref-proc.php` extract stack cards into `mds/HyperTalkReference/*.json`.
  - `scripts/generate-json.php` writes Markdown into `store/HyperTalkReference/{section}/{card}.md`, adds examples/demo sections, embeds placeholders with `[embed:HelpExtras/Placeholders/{name}.md]`, and adds related-topic links.
- Help Extras generation:
  - `scripts/topics-extra.php` writes section topic indexes under `data/HelpExtras-*-topics.json`.
  - `scripts/new-extras-proc-glossary.php`, `scripts/new-extras-proc-tips.php`, `scripts/new-extras-proc-troubles.php`, and `scripts/new-extras-proc.php` extract Help Extras cards into `mds/HelpExtras/{section}/*.json`.
  - `scripts/generate-glossary-mds.php`, `scripts/generate-tips-mds.php`, `scripts/generate-troubleshooting-mds.php`, and `scripts/generate-ph-mds.php` write Markdown into `store/HelpExtras/{section}/*.md`.
- Be careful with generation scripts: they write into the nested `store/` repo and some scripts are rough/legacy. `scripts/topics.php` intentionally exits with `destructive`; `scripts/topics-extra.php` currently initializes `Placeholder` but writes `Placeholders`, so verify/fix that before relying on the placeholders topic index.
- `mds/TODO.md` currently lists small content/link TODOs.

## Frontend/UI

- The site deliberately supports a retro HTML/table/font-tag look and a modern Bootstrap-based look.
- Modern rendering currently loads Bootstrap 4.6.1 and jQuery 3.6.0 from CDNs, even though `package.json` installs Bootstrap 5.1.3, jQuery, and Font Awesome locally.
- Static assets are under `web/ui/`. Several older root-level asset paths appear to have been moved into `web/` in the current working tree.
- `version` contains the displayed site version (`0.8b4` at the time these notes were written).

## Local Development

- Install PHP dependencies with `composer install` if `vendor/` is absent.
- Install Node assets with `npm install` if `node_modules/` is absent, though current rendered pages primarily use CDN assets.
- A typical local server command from the repository root is:

```sh
php -S 127.0.0.1:8000 -t web
```

- Runtime logs and hit files are written under `cache/`; make sure that directory exists and is writable.
- The app may require local DB settings in `code/site.inc.php` for routes that touch `$SITE['db']`, but many public reference pages are file-backed.

## Agent Guidance

- Preserve the old-school HyperCard feel unless the user explicitly asks for redesign work.
- Be careful with global state: routes and pages rely on globals such as `$SITE`, `$opt`, `$PATH`, `$section_link`, and `$card_link`.
- When editing routes or page rendering, test both modern and retro view modes when feasible (`?view=modern` and `?view=retro`).
- Avoid broad refactors. Much of the code is legacy PHP with intentional compatibility quirks and mixed content-conversion logic.
- Before making changes, check `git status`; this repo may already contain user changes such as files moved from the root into `web/`.