baldart 3.6.2

package/framework/.claude/skills/copywriting/references/copy-frameworks.md

@@ -0,0 +1,338 @@
+# Copy Frameworks Reference
+
+Headline formulas, page section types, and structural templates.
+
+## Headline Formulas
+
+### Outcome-Focused
+
+**{Achieve desirable outcome} without {pain point}**
+> Understand how users are really experiencing your site without drowning in numbers
+
+**{Achieve desirable outcome} by {how product makes it possible}**
+> Generate more leads by seeing which companies visit your site
+
+**Turn {input} into {outcome}**
+> Turn your hard-earned sales into repeat customers
+
+**[Achieve outcome] in [timeframe]**
+> Get your tax refund in 10 days
+
+---
+
+### Problem-Focused
+
+**Never {unpleasant event} again**
+> Never miss a sales opportunity again
+
+**{Question highlighting the main pain point}**
+> Hate returning stuff to Amazon?
+
+**Stop [pain]. Start [pleasure].**
+> Stop chasing invoices. Start getting paid on time.
+
+---
+
+### Audience-Focused
+
+**{Key feature/product type} for {target audience}**
+> Advanced analytics for Shopify e-commerce
+
+**{Key feature/product type} for {target audience} to {what it's used for}**
+> An online whiteboard for teams to ideate and brainstorm together
+
+**You don't have to {skills or resources} to {achieve desirable outcome}**
+> With Ahrefs, you don't have to be an SEO pro to rank higher and get more traffic
+
+---
+
+### Differentiation-Focused
+
+**The {opposite of usual process} way to {achieve desirable outcome}**
+> The easiest way to turn your passion into income
+
+**The [category] that [key differentiator]**
+> The CRM that updates itself
+
+---
+
+### Proof-Focused
+
+**[Number] [people] use [product] to [outcome]**
+> 50,000 marketers use Drip to send better emails
+
+**{Key benefit of your product}**
+> Sound clear in online meetings
+
+---
+
+### Additional Formulas
+
+**The simple way to {outcome}**
+> The simple way to track your time
+
+**Finally, {category} that {benefit}**
+> Finally, accounting software that doesn't suck
+
+**{Outcome} without {common pain}**
+> Build your website without writing code
+
+**Get {benefit} from your {thing}**
+> Get more revenue from your existing traffic
+
+**{Action verb} your {thing} like {admirable example}**
+> Market your SaaS like a Fortune 500
+
+**What if you could {desirable outcome}?**
+> What if you could close deals 30% faster?
+
+**Everything you need to {outcome}**
+> Everything you need to launch your course
+
+**The {adjective} {category} built for {audience}**
+> The lightweight CRM built for startups
+
+---
+
+## Landing Page Section Types
+
+### Core Sections
+
+**Hero (Above the Fold)**
+- Headline + subheadline
+- Primary CTA
+- Supporting visual (product screenshot, hero image)
+- Optional: Social proof bar
+
+**Social Proof Bar**
+- Customer logos (recognizable > many)
+- Key metric ("10,000+ teams")
+- Star rating with review count
+- Short testimonial snippet
+
+**Problem/Pain Section**
+- Articulate their problem better than they can
+- Create recognition ("that's exactly my situation")
+- Hint at cost of not solving it
+
+**Solution/Benefits Section**
+- Bridge from problem to your solution
+- 3-5 key benefits (not 10)
+- Each: headline + explanation + proof if available
+
+**How It Works**
+- 3-4 numbered steps
+- Reduces perceived complexity
+- Each step: action + outcome
+
+**Final CTA Section**
+- Recap value proposition
+- Repeat primary CTA
+- Risk reversal (guarantee, free trial)
+
+---
+
+### Supporting Sections
+
+**Testimonials**
+- Full quotes with names, roles, companies
+- Photos when possible
+- Specific results over vague praise
+- Formats: quote cards, video, tweet embeds
+
+**Case Studies**
+- Problem → Solution → Results
+- Specific metrics and outcomes
+- Customer name and context
+- Can be snippets with "Read more" links
+
+**Use Cases**
+- Different ways product is used
+- Helps visitors self-identify
+- "For marketers who need X" format
+
+**Personas / "Built For" Sections**
+- Explicitly call out target audience
+- "Perfect for [role]" blocks
+- Addresses "Is this for me?" question
+
+**FAQ Section**
+- Address common objections
+- Good for SEO
+- Reduces support burden
+- 5-10 most common questions
+
+**Comparison Section**
+- vs. competitors (name them or don't)
+- vs. status quo (spreadsheets, manual processes)
+- Tables or side-by-side format
+
+**Integrations / Partners**
+- Logos of tools you connect with
+- "Works with your stack" messaging
+- Builds credibility
+
+**Founder Story / Manifesto**
+- Why you built this
+- What you believe
+- Emotional connection
+- Differentiates from faceless competitors
+
+**Demo / Product Tour**
+- Interactive demos
+- Video walkthroughs
+- GIF previews
+- Shows product in action
+
+**Pricing Preview**
+- Teaser even on non-pricing pages
+- Starting price or "from $X/mo"
+- Moves decision-makers forward
+
+**Guarantee / Risk Reversal**
+- Money-back guarantee
+- Free trial terms
+- "Cancel anytime"
+- Reduces friction
+
+**Stats Section**
+- Key metrics that build credibility
+- "10,000+ customers"
+- "4.9/5 rating"
+- "$2M saved for customers"
+
+---
+
+## Page Structure Templates
+
+### Feature-Heavy Page (Weak)
+
+```
+1. Hero
+2. Feature 1
+3. Feature 2
+4. Feature 3
+5. Feature 4
+6. CTA
+```
+
+This is a list, not a persuasive narrative.
+
+---
+
+### Varied, Engaging Page (Strong)
+
+```
+1. Hero with clear value prop
+2. Social proof bar (logos or stats)
+3. Problem/pain section
+4. How it works (3 steps)
+5. Key benefits (2-3, not 10)
+6. Testimonial
+7. Use cases or personas
+8. Comparison to alternatives
+9. Case study snippet
+10. FAQ
+11. Final CTA with guarantee
+```
+
+This tells a story and addresses objections.
+
+---
+
+### Compact Landing Page
+
+```
+1. Hero (headline, subhead, CTA, image)
+2. Social proof bar
+3. 3 key benefits with icons
+4. Testimonial
+5. How it works (3 steps)
+6. Final CTA with guarantee
+```
+
+Good for ad landing pages where brevity matters.
+
+---
+
+### Enterprise/B2B Landing Page
+
+```
+1. Hero (outcome-focused headline)
+2. Logo bar (recognizable companies)
+3. Problem section (business pain)
+4. Solution overview
+5. Use cases by role/department
+6. Security/compliance section
+7. Integration logos
+8. Case study with metrics
+9. ROI/value section
+10. Contact/demo CTA
+```
+
+Addresses enterprise buyer concerns.
+
+---
+
+### Product Launch Page
+
+```
+1. Hero with launch announcement
+2. Video demo or walkthrough
+3. Feature highlights (3-5)
+4. Before/after comparison
+5. Early testimonials
+6. Launch pricing or early access offer
+7. CTA with urgency
+```
+
+Good for ProductHunt, launches, or announcements.
+
+---
+
+## Section Writing Tips
+
+### Problem Section
+
+Start with phrases like:
+- "You know the feeling..."
+- "If you're like most [role]..."
+- "Every day, [audience] struggles with..."
+- "We've all been there..."
+
+Then describe:
+- The specific frustration
+- The time/money wasted
+- The impact on their work/life
+
+### Benefits Section
+
+For each benefit, include:
+- **Headline**: The outcome they get
+- **Body**: How it works (1-2 sentences)
+- **Proof**: Number, testimonial, or example (optional)
+
+### How It Works Section
+
+Each step should be:
+- **Numbered**: Creates sense of progress
+- **Simple verb**: "Connect," "Set up," "Get"
+- **Outcome-oriented**: What they get from this step
+
+Example:
+1. Connect your tools (takes 2 minutes)
+2. Set your preferences
+3. Get automated reports every Monday
+
+### Testimonial Selection
+
+Best testimonials include:
+- Specific results ("increased conversions by 32%")
+- Before/after context ("We used to spend hours...")
+- Role + company for credibility
+- Something quotable and specific
+
+Avoid testimonials that just say:
+- "Great product!"
+- "Love it!"
+- "Easy to use!"

package/framework/.claude/skills/copywriting/references/natural-transitions.md

@@ -0,0 +1,252 @@
+# Natural Transitions
+
+Transitional phrases to guide readers through your content. Good signposting improves readability, user engagement, and helps search engines understand content structure.
+
+Adapted from: University of Manchester Academic Phrasebank (2023), Plain English Campaign, web content best practices
+
+---
+
+## Previewing Content Structure
+
+Use to orient readers and set expectations:
+
+- Here's what we'll cover...
+- This guide walks you through...
+- Below, you'll find...
+- We'll start with X, then move to Y...
+- First, let's look at...
+- Let's break this down step by step.
+- The sections below explain...
+
+---
+
+## Introducing a New Topic
+
+- When it comes to X,...
+- Regarding X,...
+- Speaking of X,...
+- Now let's talk about X.
+- Another key factor is...
+- X is worth exploring because...
+
+---
+
+## Referring Back
+
+Use to connect ideas and reinforce key points:
+
+- As mentioned earlier,...
+- As we covered above,...
+- Remember when we discussed X?
+- Building on that point,...
+- Going back to X,...
+- Earlier, we explained that...
+
+---
+
+## Moving Between Sections
+
+- Now let's look at...
+- Next up:...
+- Moving on to...
+- With that covered, let's turn to...
+- Now that you understand X, here's Y.
+- That brings us to...
+
+---
+
+## Indicating Addition
+
+- Also,...
+- Plus,...
+- On top of that,...
+- What's more,...
+- Another benefit is...
+- Beyond that,...
+- In addition,...
+- There's also...
+
+**Note:** Use "moreover" and "furthermore" sparingly. They can sound AI-generated when overused.
+
+---
+
+## Indicating Contrast
+
+- However,...
+- But,...
+- That said,...
+- On the flip side,...
+- In contrast,...
+- Unlike X, Y...
+- While X is true, Y...
+- Despite this,...
+
+---
+
+## Indicating Similarity
+
+- Similarly,...
+- Likewise,...
+- In the same way,...
+- Just like X, Y also...
+- This mirrors...
+- The same applies to...
+
+---
+
+## Indicating Cause and Effect
+
+- So,...
+- This means...
+- As a result,...
+- That's why...
+- Because of this,...
+- This leads to...
+- The outcome?...
+- Here's what happens:...
+
+---
+
+## Giving Examples
+
+- For example,...
+- For instance,...
+- Here's an example:...
+- Take X, for instance.
+- Consider this:...
+- A good example is...
+- To illustrate,...
+- Like when...
+- Say you want to...
+
+---
+
+## Emphasising Key Points
+
+- Here's the key takeaway:...
+- The important thing is...
+- What matters most is...
+- Don't miss this:...
+- Pay attention to...
+- This is critical:...
+- The bottom line?...
+
+---
+
+## Providing Evidence
+
+Use when citing sources, data, or expert opinions:
+
+### Neutral attribution
+- According to [Source],...
+- [Source] reports that...
+- Research shows that...
+- Data from [Source] indicates...
+- A study by [Source] found...
+
+### Expert quotes
+- As [Expert] puts it,...
+- [Expert] explains,...
+- In the words of [Expert],...
+- [Expert] notes that...
+
+### Supporting claims
+- This is backed by...
+- Evidence suggests...
+- The numbers confirm...
+- This aligns with findings from...
+
+---
+
+## Summarising Sections
+
+- To recap,...
+- Here's the short version:...
+- In short,...
+- The takeaway?...
+- So what does this mean?...
+- Let's pull this together:...
+- Quick summary:...
+
+---
+
+## Concluding Content
+
+- Wrapping up,...
+- The bottom line is...
+- Here's what to do next:...
+- To sum up,...
+- Final thoughts:...
+- Ready to get started?...
+- Now it's your turn.
+
+**Note:** Avoid "In conclusion" at the start of a paragraph. It's overused and signals AI writing.
+
+---
+
+## Question-Based Transitions
+
+Useful for conversational tone and featured snippet optimization:
+
+- So what does this mean for you?
+- But why does this matter?
+- How do you actually do this?
+- What's the catch?
+- Sound complicated? It's not.
+- Wondering where to start?
+- Still not sure? Here's the breakdown.
+
+---
+
+## List Introductions
+
+For numbered lists and step-by-step content:
+
+- Here's how to do it:
+- Follow these steps:
+- The process is straightforward:
+- Here's what you need to know:
+- Key things to consider:
+- The main factors are:
+
+---
+
+## Hedging Language
+
+For claims that need qualification or aren't absolute:
+
+- may, might, could
+- tends to, generally
+- often, usually, typically
+- in most cases
+- it appears that
+- evidence suggests
+- this can help
+- many experts believe
+
+---
+
+## Best Practice Guidelines
+
+1. **Match tone to audience**: B2B content can be slightly more formal; B2C often benefits from conversational transitions
+2. **Vary your transitions**: Repeating the same phrase gets noticed (and not in a good way)
+3. **Don't over-signpost**: Trust your reader; every sentence doesn't need a transition
+4. **Use for scannability**: Transitions at paragraph starts help skimmers navigate
+5. **Keep it natural**: Read aloud; if it sounds forced, simplify
+6. **Front-load key info**: Put the important word or phrase early in the transition
+
+---
+
+## Transitions to Avoid (AI Tells)
+
+These phrases are overused in AI-generated content:
+
+- "That being said,..."
+- "It's worth noting that..."
+- "At its core,..."
+- "In today's digital landscape,..."
+- "When it comes to the realm of..."
+- "This begs the question..."
+- "Let's delve into..."
+
+See the seo-audit skill's `references/ai-writing-detection.md` for a complete list of AI writing tells.

package/framework/.claude/skills/doc-writing-for-rag/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: doc-writing-for-rag
+description: "Scrive documentazione di reference ad alta densità ottimizzata per RAG indexing. Usa template compatti, frontmatter minimal, cross-reference a schemas.md/errors.md (paths da `paths.api_schemas`/`paths.api_errors` in `baldart.config.yml`). Carica questa skill quando crei o riscrivi file in `${paths.references_dir}`, `${paths.prd_dir}`, o quando senti 'template endpoint', 'compattare docs', 'doc per RAG', 'dense documentation', 'signal/noise ratio'."
+---
+
+# Doc Writing for RAG
+
+Protocollo di scrittura per reference docs ottimizzate per LightRAG indexing. Validato su 45 file in 3 wave di compressione (-48% linee medio, signal/noise da 45% a 80%+).
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `paths.references_dir`, `paths.api_schemas`, `paths.api_errors`, `paths.prd_dir`.
+**Gated by features:** `features.has_api_docs` (schemas/errors workflow active when `true`; otherwise the skill skips schemas.md / errors.md cross-references and writes self-contained endpoint docs).
+**Overlay:** loads `.baldart/overlays/doc-writing-for-rag.md` if present — project-specific domain list, schema naming conventions, frontmatter extensions.
+**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
+
+## When to Use
+
+Carica questa skill quando:
+
+- **Nuovo reference doc** da scrivere (es. nuovo dominio API, UI page, collection)
+- **Major rewrite** di file esistente >1500 linee o con S/N basso
+- **Nuovo endpoint API** da documentare in file esistente
+- **Extending** `schemas.md` o `errors.md` con nuovi schemi/codes
+
+NON caricare per:
+- Review incrementale di file esistenti (usa doc-reviewer-support)
+- Scrittura di ADR (diversi, già densi, vedi writing-guide)
+- PRD discovery/ideation (usa prd skill)
+- Business/marketing copy (usa copywriting skill)
+
+## Core Principles
+
+1. **Cross-reference over repetition**: un concetto spiegato UNA VOLTA, linkato altrove
+2. **Tables > prose** per info strutturate (endpoint params, error codes, schemas)
+3. **Frontmatter minimo**: 4 campi (doc_type, domain, canonicality, last_updated). Niente audit_notes, freshness_status, stale_*, owner, status (derivabili da git)
+4. **Central support files**: `schemas.md` per JSON schemas riusabili, `errors.md` per error codes
+5. **Line count targets**: API ref <1500, PRD <1500, ADR <200, index <500
+6. **Descrittivo ma denso**: preserva TUTTA l'info semantica, comprimi solo verbosità
+
+## Workflow — Nuovo endpoint API
+
+1. **Check schemas.md** (`${paths.api_schemas}`): lo schema response esiste già? Se sì, riusalo. Se no, definiscilo DOPO aver scritto l'endpoint, in APPEND alla sezione di dominio appropriata. (Skip when `features.has_api_docs: false`.)
+
+2. **Check errors.md** (`${paths.api_errors}`): gli error codes esistono già nella domain section? Se sì, riusali. Se no, aggiungili APPEND in domain section. (Skip when `features.has_api_docs: false`.)
+
+3. **Scrivi endpoint con template compatto**:
+   ```markdown
+   ### POST /api/v1/domain/resource
+
+   **Auth**: withAuthNoParams  |  **Access**: ADMIN + MERCHANT
+
+   **Body**:
+   | Field | Type | Required | Desc |
+   |-------|------|----------|------|
+   | storeId | string | yes | Store UUID |
+   | name | string | yes | Display name |
+
+   **Returns**: [ResourceResponse](./schemas.md#resourceresponse)
+   **Errors**: RESOURCE_NOT_FOUND, INVALID_NAME ([errors.md](../errors.md#domain-domain))
+   ```
+
+4. **Path relativi corretti** (dipende dalla location del file):
+   - `api/*.md` → `./schemas.md` + `../errors.md`
+   - `api/booking/*.md` → `../schemas.md` + `../../errors.md`
+   - `api/survey/*.md` → `../schemas.md` + `../../errors.md`
+
+5. **Verifica line count**: se il file supera 1500 linee → split in sub-files per dominio.
+
+## Template snippets inline
+
+### Frontmatter minimo (mandatory)
+
+```yaml
+---
+doc_type: reference
+domain: booking
+canonicality: canonical-source
+last_updated: 2026-04-05
+---
+```
+
+Altri campi (owner, status, audit_notes, freshness_status, stale_*) sono **derivabili** da git blame / tooling → **non scriverli**.
+
+### Compact endpoint (mandatory)
+
+```markdown
+### VERB /path
+
+**Auth**: hook  |  **Access**: roles
+
+**Body** / **Query** / **Params**: tabella 4 colonne
+
+**Returns**: [Schema](schemas#anchor)
+**Errors**: CODE1, CODE2 ([errors.md](errors#domain))
+```
+
+### Cross-reference section (per concetti ripetuti)
+
+Spiegazione completa **una sola volta** nella intro del file, poi:
+```markdown
+See [§Store Access Control](#store-access-control) for gating details.
+```
+
+## Reference files (on-demand loading)
+
+| Reference | When to load |
+|-----------|--------------|
+| `references/compact-templates.md` | Scrittura nuovo endpoint/UI/PRD/collection |
+| `references/schemas-and-errors.md` | Estensione di schemas.md o errors.md |
+| `references/frontmatter-minimal.md` | Definire frontmatter di un nuovo file |
+| `references/line-count-targets.md` | File > soglia, decidere se splittare |
+| `references/before-after-examples.md` | Vuoi esempi concreti Wave 1+2+3 |
+
+## Related Skills
+
+- `doc-reviewer-support`: review checklists, invariant tables, navigation audit
+- `prd`: PRD discovery & ideation (diverso scope)
+- `copywriting`: marketing/UX copy