DMleadgen
3cb8d3cb3f
- Schema.org JSON-LD templates (product, event, local-business, faq) - Brand, UI, SEO, and decision guide rules - Working code snippets (vendor-card, schema-inject, deploy-webhook) - JSON schemas for project config validation - Client presets (slc-bride, default) - Self-update protocol with changelog tracking Made-with: Cursor
166 lines
4.1 KiB
Markdown
166 lines
4.1 KiB
Markdown
# AI Decision Guide
|
|
|
|
This document maps common scenarios to the correct tools and patterns.
|
|
|
|
---
|
|
|
|
## Adding a New Page
|
|
|
|
1. Check `.ai-context.json` for route patterns
|
|
2. Read brand preset from `presets/<client>.json`
|
|
3. Copy structure from `snippets/` similar pages
|
|
4. Add schema from `templates/` if SEO-relevant
|
|
5. Follow heading hierarchy from `rules/seo-rules.md`
|
|
|
|
---
|
|
|
|
## Deploying Changes
|
|
|
|
### ALWAYS follow this sequence:
|
|
|
|
```bash
|
|
# Step 1: Deploy to staging
|
|
deploy_push({ target: "staging", app_id: "<from .ai-cli.json>" })
|
|
|
|
# Step 2: Verify on staging URL
|
|
# Check: functionality, styling, data loading
|
|
|
|
# Step 3: If successful, deploy to prod
|
|
deploy_push({ target: "prod", app_id: "<from .ai-cli.json>" })
|
|
```
|
|
|
|
### Never skip staging deployment for production changes.
|
|
|
|
---
|
|
|
|
## Fixing Brand/Style Issues
|
|
|
|
1. Read `presets/<client>.json` for brand rules
|
|
2. Check `rules/ui-fixes.json` for patterns
|
|
3. Use shadcn MCP for component updates
|
|
4. Verify dark mode support if applicable
|
|
|
|
### Common Patterns:
|
|
| Issue | Solution |
|
|
|-------|----------|
|
|
| Colors not matching | Check CSS variables match preset |
|
|
| Font not loading | Verify Google Fonts import |
|
|
| Spacing inconsistent | Use Tailwind spacing scale |
|
|
|
|
---
|
|
|
|
## Adding Structured Data
|
|
|
|
1. Fetch template: `seo_add_schema({ template: "product", data: {...} })`
|
|
2. Template pulled from Forgejo with current brand
|
|
3. Inject into page `<head>` as JSON-LD script tag
|
|
4. Validate with Google Rich Results Test
|
|
|
|
### Template Selection:
|
|
| Content Type | Template |
|
|
|--------------|----------|
|
|
| Product/Service | `schema-product.json` |
|
|
| Event | `schema-event.json` |
|
|
| Business Listing | `schema-local-business.json` |
|
|
| FAQ Section | `schema-faq.json` |
|
|
|
|
---
|
|
|
|
## Database Operations
|
|
|
|
1. Read `.ai-cli.json` for database connection info
|
|
2. Use `supabase_query` with parameterized queries only
|
|
3. **NEVER** use string concatenation for queries
|
|
4. Check RLS policies if query fails
|
|
|
|
### Safe Query Pattern:
|
|
```javascript
|
|
// Correct
|
|
supabase_query({
|
|
query: "SELECT * FROM vendors WHERE category = $1 AND active = $2",
|
|
params: ["photography", true]
|
|
})
|
|
|
|
// WRONG - Never do this
|
|
supabase_query({
|
|
query: `SELECT * FROM vendors WHERE category = '${category}'`
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## Creating New Components
|
|
|
|
1. Check `snippets/` for existing similar components
|
|
2. Follow brand preset for styling
|
|
3. Use shadcn/ui as base when possible
|
|
4. Add accessibility attributes (see `rules/ui-fixes.json`)
|
|
5. After creation, update context:
|
|
```
|
|
context_update({
|
|
file: "snippets/components.md",
|
|
section: "new-components",
|
|
content: { name: "ComponentName", path: "..." }
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## Handling Errors
|
|
|
|
### Step 1: Identify Error Type
|
|
| Error Type | Check |
|
|
|------------|-------|
|
|
| Type Error | TypeScript interfaces, props |
|
|
| Runtime Error | Console logs, stack trace |
|
|
| Build Error | Dependencies, env vars |
|
|
| Database Error | RLS policies, query syntax |
|
|
|
|
### Step 2: Check Common Fixes
|
|
Look in `rules/common-fixes.md` for known solutions
|
|
|
|
### Step 3: If New Pattern Found
|
|
1. Document the fix
|
|
2. Update `rules/common-fixes.md`
|
|
3. Run `context_update` to log the change
|
|
|
|
---
|
|
|
|
## Context Update Required When
|
|
|
|
| Event | Action |
|
|
|-------|--------|
|
|
| New feature added | Update client's SKILL.md |
|
|
| Bug fix discovered | Add to `rules/common-fixes.md` |
|
|
| Brand changed | Update `presets/<client>.json` |
|
|
| New component pattern | Add to `snippets/` |
|
|
| New API endpoint | Add to `.ai-cli.json` |
|
|
| Database schema change | Update relevant schemas |
|
|
|
|
### After ANY context update:
|
|
1. Update `context/CHANGELOG.md`
|
|
2. Update `last_updated` in `_meta` section
|
|
3. Notify user if major change
|
|
|
|
---
|
|
|
|
## Tool Selection Quick Reference
|
|
|
|
| Task | Tool |
|
|
|------|------|
|
|
| Check MCP connection | `ping()` |
|
|
| Deploy app | `deploy_push()` |
|
|
| Add SEO schema | `seo_add_schema()` |
|
|
| Query database | `supabase_query()` |
|
|
| Update context files | `context_update()` |
|
|
| UI components/themes | shadcn MCP |
|
|
| File operations | filesystem MCP |
|
|
|
|
---
|
|
|
|
## Emergency Contacts
|
|
|
|
If unable to resolve:
|
|
1. Check server logs: `abundance docker logs <server> <container> -f --tail 100`
|
|
2. Check health: `abundance health check`
|
|
3. Escalate with full error context
|