feat: Improved folder naming and added README documentation

Author: kevinwang5658

CLAUDE.md

@@ -283,6 +283,36 @@ Deployment (`scripts/deploy.ts`) uploads the built plugin to Cloudflare R2:
 - Production: `plugins/{name}/{version}/index.js`
 - Beta: `plugins/{name}/beta/index.js`
 
+## Completions System
+
+The Codify Editor supports auto-complete for certain resource parameters (e.g. Homebrew formula names, Node.js versions). These completions are pre-fetched by a Cloudflare Workers cron job that lives in `completions-cron/`.
+
+### Adding completions for a parameter
+
+1. Create `src/resources/<category>/<resource>/completions/<type>.<param>.ts`
+2. Export a default async function returning `Promise<string[]>` — fetch the values, return them, nothing else
+3. The filename determines the Supabase metadata automatically:
+   - `homebrew.formulae.ts` → `resource_type=homebrew`, `parameter_path=/formulae`
+4. Run `npm run build:completions` to regenerate the index
+
+```bash
+npm run build:completions   # regenerate completions-cron/src/__generated__/completions-index.ts
+npm run deploy:completions  # build + deploy to Cloudflare Workers
+```
+
+### How it fits together
+
+```
+src/resources/**/completions/*.ts   ← per-resource fetch scripts (return string[])
+        ↓  npm run build:completions
+completions-cron/src/__generated__/completions-index.ts   ← AUTO-GENERATED, do not edit
+completions-cron/src/index.ts       ← orchestrator: Supabase writes, scheduled handler
+        ↓  wrangler deploy
+Cloudflare Workers (runs daily at 05:00 UTC)
+```
+
+See `completions-cron/README.md` for full details.
+
 ## Key Patterns
 
 ### allowMultiple Configuration
@@ -402,10 +432,17 @@ The framework automatically validates dependencies exist and orders execution.
 **Build:**
 - `/scripts/build.ts` - Build process with schema collection
 - `/scripts/deploy.ts` - Deployment to Cloudflare R2
+- `/scripts/generate-completions-index.ts` - Generates completions-cron entry index
 - `/rollup.config.js` - Bundling configuration
 - `/tsconfig.json` - TypeScript config (ES2024, strict mode)
 - `/vitest.config.ts` - Test runner config
 
+**Completions cron:**
+- `/completions-cron/src/index.ts` - Cloudflare Workers scheduled handler
+- `/completions-cron/src/__generated__/completions-index.ts` - Auto-generated, do not edit
+- `/completions-cron/wrangler.toml` - Worker config (schedule, env vars)
+- `/completions-cron/README.md` - Full documentation
+
 **Testing:**
 - `/test/setup.ts` - Global test setup/teardown
 - `/test/test-utils.ts` - Test helpers

completions-cron/.vscode/settings.json

@@ -0,0 +1,84 @@
+# resource-completions-cron
+
+A Cloudflare Workers scheduled job that pre-fetches auto-complete values for resource parameters in the Codify Editor. It runs daily and writes results to the `resource_parameter_completions` Supabase table.
+
+## How It Works
+
+### 1. Per-resource completion scripts
+
+Each resource that supports completions has one or more scripts co-located with it in the plugin:
+
+```
+codify-homebrew-plugin/src/resources/
+  homebrew/completions/
+    homebrew.formulae.ts     → resource_type=homebrew, parameter_path=/formulae
+    homebrew.casks.ts        → resource_type=homebrew, parameter_path=/casks
+  javascript/nvm/completions/
+    nvm.nodeVersions.ts      → resource_type=nvm,      parameter_path=/nodeVersions
+  python/pyenv/completions/
+    pyenv.pythonVersions.ts  → resource_type=pyenv,    parameter_path=/pythonVersions
+```
+
+**Naming convention:** `<resource-type>.<parameter-name>.ts`
+- The filename determines the Supabase metadata — no configuration needed
+- Each file exports a single `default async function(): Promise<string[]>` that fetches and returns the completion values. It has no knowledge of Supabase.
+
+### 2. Code generation
+
+Running `npm run build:completions` (from the plugin root) executes `scripts/generate-completions-index.ts`, which:
+- Globs all `src/resources/**/completions/*.ts` files in the plugin
+- Parses each filename for `resourceType` and `parameterPath`
+- Writes `src/__generated__/completions-index.ts` — a static list of imports and metadata
+
+`src/__generated__/completions-index.ts` is auto-generated. **Do not edit it by hand.**
+
+### 3. Orchestrator
+
+`src/index.ts` is the Cloudflare Workers entry point. It:
+- Imports `completionModules` from the generated index
+- For each module, calls the `fetch()` function to get `string[]` values
+- Looks up the `resource_id` from the `registry_resources` Supabase table
+- Deletes old completions and batch-inserts new ones (1000 rows per batch) into `resource_parameter_completions`
+- Runs all modules concurrently via `Promise.allSettled`
+
+## Commands
+
+All commands are run from the **plugin root** (`codify-homebrew-plugin/`):
+
+```bash
+# Regenerate src/__generated__/completions-index.ts
+npm run build:completions
+
+# Build + deploy to Cloudflare Workers
+npm run deploy:completions
+```
+
+To run/test locally (from this directory):
+
+```bash
+# Start local wrangler dev server with scheduled trigger support
+npm run dev
+
+# Trigger the scheduled handler manually against the local server
+npm run start:cron
+```
+
+## Adding a New Completion
+
+1. Create `src/resources/<category>/<resource>/completions/<type>.<param>.ts` in the plugin
+2. Export a default async function returning `string[]`
+3. Run `npm run build:completions` from the plugin root to regenerate the index
+4. Run `npm run deploy:completions` to deploy
+
+No changes are needed to any file in this directory.
+
+## Environment Variables
+
+| Variable | Where set |
+|---|---|
+| `SUPABASE_URL` | `wrangler.toml` `[vars]` (public URL, safe to commit) |
+| `SUPABASE_SERVICE_ROLE_KEY` | Cloudflare Workers secret (set via `wrangler secret put`) |
+
+## Schedule
+
+The cron runs daily at 05:00 UTC (`0 5 * * *`), configured in `wrangler.toml`.