@ai.all/ds7 0.0.0-stage → 2.0.0

package/04-seo-ai-optimization/AEO-GEO-AI-SEARCH.md

@@ -0,0 +1,53 @@
+# 04 · AEO and GEO: writing for AI search engines
+
+Answer Engine Optimization (AEO) and Generative Engine Optimization (GEO) make a site easy to quote in AI answers: ChatGPT search, Perplexity, Gemini overviews and similar systems.
+
+---
+
+## 1. What changed
+
+Classic search matched words. AI search extracts **claims and facts** that answer a question, then cites the source. Pages that state a question, answer it in a few precise sentences, and back it with structured data are quoted more often.
+
+---
+
+## 2. Direct answer block
+
+Each informational section begins with its question as an `h2` and a short factual answer of 40–50 words:
+
+```html
+<h2 id="cost-4kw">How much does a 4 kW home solar system cost?</h2>
+
+<p class="direct-answer">
+  A standard 4 kW system costs <strong>[range from your price list]</strong> before grants.
+  Replace the placeholder with a figure you can source, and state the date and the region.
+</p>
+```
+
+Rules for the answer:
+- No introduction ("Great question…"). The first words answer the question.
+- Numbers come with units, a date and a region.
+- Every figure has a source in the page or in linked official documents.
+
+---
+
+## 3. Tables for comparisons
+
+Assistants parse tables faster than prose. Use real `<table>` markup with `<thead>`:
+
+| Model | Power | Efficiency | Warranty |
+|---|---|---|---|
+| [example] | [value] | [value] | [value] |
+
+Fill in values from your product data, not from this example.
+
+---
+
+## 4. Sources
+
+Name primary sources: the law, the official gazette, the grant programme page. Link them. A claim with a link to the regulation is quoted more often than one without.
+
+---
+
+## 5. Measurement
+
+Track which pages appear in AI answers with a manual check each month, and record it in the project's `docs/METRICS.md`. Do not record a figure you did not observe.

package/04-seo-ai-optimization/GOOGLE-LOCAL-EEAT.md

@@ -0,0 +1,36 @@
+# 04 · Local search, E-E-A-T and behavioural signals
+
+For businesses that serve a region, most new customers find them through a map listing. This document lists what the site controls.
+
+---
+
+## 1. Local pack
+
+Google's local results use the business profile and the website together.
+
+1. **NAP consistency.** Name, address and phone are identical on the website, in `LocalBusiness` structured data and in the business profile. Same spelling, same format.
+2. **Reviews.** Real customer reviews, requested after each job. Do not write reviews for customers and do not ask for reviews only from happy customers.
+3. **Service areas.** The towns or regions served are listed in the page content and in the structured data (`areaServed`).
+
+---
+
+## 2. E-E-A-T
+
+Google rates the trustworthiness of pages that affect money or safety more strictly.
+
+- **Legal identity:** full legal name, company registration number, registered address. Shown in the footer and on a legal page.
+- **Qualifications:** the licences and certifications the staff hold, with the issuing body named.
+- **Partnerships:** only partner logos the business is authorised to use, with a link to the partner's confirmation where one exists.
+- **Named authors** for guides, with their role.
+
+Placeholders in this standard (`[Legal name]`, `[Registration number]`) must be replaced with real data by the business.
+
+---
+
+## 3. Behavioural signals
+
+Google observes what visitors do after a result.
+
+- **Fast first content.** A visitor who sees content at once stays. See `03-performance-web-vitals/`.
+- **Useful interaction.** A calculator or configurator keeps a visitor on the page to finish a task.
+- **Completed intent.** A visitor who reaches the contact action or downloads what they came for does not need to search again. Design the contact action to be the obvious next step.

package/04-seo-ai-optimization/STRUCTURED-DATA.md

@@ -0,0 +1,95 @@
+# 04 · Structured data (Schema.org JSON-LD)
+
+Structured data is a machine-readable description of the business, its products and its pages. Search engines and AI assistants use it to identify entities and to show rich results.
+
+---
+
+## 1. One graph per site
+
+Describe all entities in a single `@graph` that links them by `@id`, instead of scattered fragments:
+
+```json
+{
+  "@context": "https://schema.org",
+  "@graph": [
+    {
+      "@type": "Organization",
+      "@id": "https://example.com/#organization",
+      "name": "[Brand name]",
+      "legalName": "[Legal name]",
+      "url": "https://example.com",
+      "logo": "https://example.com/brand/logo.svg",
+      "email": "[contact email]",
+      "address": {
+        "@type": "PostalAddress",
+        "addressLocality": "[City]",
+        "addressRegion": "[Region]",
+        "addressCountry": "[ISO country code]"
+      },
+      "areaServed": ["[Region 1]", "[Region 2]"]
+    },
+    {
+      "@type": "WebSite",
+      "@id": "https://example.com/#website",
+      "url": "https://example.com",
+      "name": "[Brand name]",
+      "publisher": { "@id": "https://example.com/#organization" },
+      "inLanguage": ["es", "en", "uk"]
+    }
+  ]
+}
+```
+
+Name, address and phone must match the business profile exactly (see `GOOGLE-LOCAL-EEAT.md`).
+
+---
+
+## 2. Products and offers
+
+```json
+{
+  "@type": "Product",
+  "name": "[Product name]",
+  "image": "https://example.com/images/p/product.webp",
+  "description": "[One factual sentence]",
+  "brand": { "@type": "Brand", "name": "[Brand]" },
+  "offers": {
+    "@type": "Offer",
+    "price": "[price]",
+    "priceCurrency": "EUR",
+    "priceValidUntil": "[date the price is valid until]",
+    "availability": "https://schema.org/InStock",
+    "seller": { "@id": "https://example.com/#organization" }
+  }
+}
+```
+
+Only publish a price that is current on the page. Update `priceValidUntil` when you update the price.
+
+---
+
+## 3. FAQ
+
+```json
+{
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "[Question as the visitor asks it]",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "[The same answer as on the page]"
+      }
+    }
+  ]
+}
+```
+
+The FAQ text in structured data must match the visible text on the page.
+
+---
+
+## 4. Validation
+
+Check every page with a structured-data validator before release. A validator error counts as a failed gate.

package/05-internationalization/I18N-ARCHITECTURE.md

@@ -0,0 +1,59 @@
+# 05 · Internationalisation: one hub
+
+All interface text lives in one place. Adding a language is one file and one configuration entry.
+
+---
+
+## 1. Principle
+
+Do not keep text in several places: partly in `i18n/`, partly in inline `{ es, en }` objects inside components, partly typed into templates.
+
+Structure:
+
+```
+i18n/
+└── locales/
+    ├── es.ts      # base language
+    ├── en.ts
+    ├── uk.ts
+    └── [code].ts  # any new language
+```
+
+---
+
+## 2. Adding a language
+
+1. Copy the base locale file to `[code].ts` and translate every value. Keys stay the same.
+2. Register the language:
+
+```ts
+// nuxt.config.ts
+i18n: {
+  strategy: 'prefix_except_default',
+  defaultLocale: 'es',
+  locales: [
+    { code: 'es', language: 'es-ES', name: 'Español', file: 'es.ts' },
+    { code: 'en', language: 'en-GB', name: 'English', file: 'en.ts' },
+    { code: 'uk', language: 'uk-UA', name: 'Українська', file: 'uk.ts' },
+    { code: '[code]', language: '[bcp47]', name: '[name]', file: '[code].ts' },
+  ],
+  langDir: '../i18n/locales',
+}
+```
+
+Routes, language switcher, `hreflang` and sitemap entries for the new language are generated from this list.
+
+---
+
+## 3. Keys
+
+- Grouped by component or section: `businessScreens.night.title`.
+- Named by meaning, never by appearance (`hero.title`, not `big.red.title`).
+- The same key set in every locale. The parity check fails the build when a key is missing.
+
+---
+
+## 4. UI strings versus business data
+
+- `i18n/locales/*.ts`: interface text only. Button labels, form labels, navigation, error messages.
+- `app/data/*.ts`: business data. Products, specifications, service areas, articles. Typed. Text fields that differ by language use an object keyed by locale, validated by the schema, so a missing translation breaks the build.

package/05-internationalization/LOCALE-TEMPLATE.json

@@ -0,0 +1,33 @@
+{
+  "_comment": "Locale template. Copy to i18n/locales/<code>.ts in your project and translate every value. Keys must match the base locale exactly.",
+  "nav": {
+    "home": "Home",
+    "residential": "Residential",
+    "business": "Business",
+    "mobility": "Mobility",
+    "equipment": "Equipment",
+    "service": "Service",
+    "contact": "Contact"
+  },
+  "common": {
+    "viewProduct": "View product",
+    "requestQuote": "Request a quote",
+    "calculate": "Calculate savings",
+    "fromPrice": "from",
+    "close": "Close",
+    "send": "Send",
+    "success": "Your request was sent"
+  },
+  "calc": {
+    "title": "Calculate your solar savings",
+    "billLabel": "How much do you pay for electricity per month?",
+    "yearlySavings": "Estimated yearly savings",
+    "recommendedPower": "Recommended capacity",
+    "paybackTime": "Estimated payback period"
+  },
+  "badges": {
+    "top": "Best seller",
+    "new": "New",
+    "sale": "Offer"
+  }
+}

package/06-business-conversion/B2C-B2B-MODELS.md

@@ -0,0 +1,37 @@
+# 06 · Commercial models for energy projects (example)
+
+> Example document from a Spanish solar company, 2025–2026. Market rules, subsidies and prices change. Verify every figure against current official sources before use.
+
+---
+
+## 1. Residential (B2C)
+
+**Virtual battery.** In sunny months a home system produces more than the household uses. The surplus goes to the grid and is credited on the customer's account. In winter the credit offsets night-time consumption.
+
+**Result for the customer:** a bill close to zero over the year, when credits match consumption.
+
+**Energy communities.** Spanish rules (RD 244/2019) allow shared self-consumption between nearby homes. Offer it to terraced houses and communities as a shared installation with a per-home discount.
+
+---
+
+## 2. Business (B2B)
+
+**Power purchase agreement (PPA).** A company that does not want to spend its own capital can have a third party install the system on its roof. The company buys the energy at a fixed rate, below the grid tariff.
+
+Explain the contract length, the rate, the escalation clause and who owns the system at the end. Do not present the rate as a saving without the tariff it is compared to.
+
+**Solar carports.** Panels over car parks for hotels, warehouses and shops. Shade for customers and staff, plus charging points for fleet vehicles.
+
+---
+
+## 3. Community and public buildings (B2A)
+
+Public programmes can fund a large share of installations for shared buildings (lifts, garages, stairwell lighting). The share and the eligibility change by programme and year. State the programme name, the year and the source.
+
+---
+
+## 4. Rules for any offer
+
+- Name the programme, the year and the official source.
+- Show the price before and after any grant as two separate figures.
+- Do not make a promise about a grant that is not yet approved.

package/06-business-conversion/CONTEXTUAL-LEADS.md

@@ -0,0 +1,45 @@
+# 06 · Contextual leads
+
+A visitor who has already used a calculator knows what they want. Contact actions should carry that context, so the first message is useful to both sides.
+
+---
+
+## 1. Contact link with context
+
+A plain `wa.me/<number>` link leaves the visitor to write the first message, and many leave. Build the message from the visitor's last action:
+
+```ts
+const contactLink = (context: {
+  page: string
+  monthlyBill?: number
+  powerKw?: number
+  productId?: string
+}) => {
+  const phone = '[international number, digits only]'
+  let text = 'Hello, I would like information. '
+  if (context.monthlyBill) {
+    text += `My monthly bill is about ${context.monthlyBill} €; the estimate was ${context.powerKw} kW. `
+  }
+  if (context.productId) {
+    text += `I am interested in: ${context.productId}. `
+  }
+  text += 'Could you confirm availability and the grants that apply?'
+  return `https://wa.me/${phone}?text=${encodeURIComponent(text)}`
+}
+```
+
+The visitor only has to press send. The message is in the visitor's language (from the i18n layer, not hard-coded).
+
+---
+
+## 2. Summary document
+
+After a calculation, offer a summary the visitor can keep: the inputs, the result, the equipment and the contact. Generate it in the browser. Ask for a phone number or email before the download, and say why.
+
+---
+
+## 3. Offline queue
+
+If the connection drops during a form submission, keep the data in `IndexedDB` (or `localStorage` for very small forms), show a neutral "saved, will be sent" message, and send it when the connection returns. A lead must not be lost because of a dropped connection.
+
+Remove stored leads after the server confirms receipt.

package/06-business-conversion/EV-SOLAR-ECOSYSTEM.md

@@ -0,0 +1,38 @@
+# 06 · Electric vehicles and solar (example)
+
+> Example from a Spanish solar company. Product names, subsidy programmes and amounts are examples. Verify them before use.
+
+---
+
+## 1. Charging from surplus solar
+
+A home charger connected to the inverter over the local network can direct surplus solar power to the car. A household that uses 1 kW while the panels make 5 kW sends the remaining 4 kW to the car.
+
+**Benefit for the customer:** the car charges from solar energy that would otherwise go to the grid.
+
+Check the compatible inverter brands before you promise this.
+
+---
+
+## 2. Show the benefit in terms people use
+
+Technical units (kW, amperes, volts) are hard to compare. Show the result in distance or money:
+
+- "Six panels on the roof give about 45 km of driving per day."
+- "Compared with petrol, the monthly saving can exceed [amount calculated for this customer]."
+
+State the assumptions next to the figure.
+
+---
+
+## 3. Vehicle-to-home (V2H)
+
+A typical home battery stores about 5 kWh. A modern electric vehicle battery stores several times more. With V2H, the car supplies the home in the evening peak or during a grid outage, if the charger and the car support it.
+
+Say which models support V2H. Do not offer it to a customer whose hardware does not.
+
+---
+
+## 4. Subsidies
+
+Public programmes can cover part of the charger and installation cost. In the example company's catalogue, each product shows two prices: the equipment price and the price after the programme's share. Show both, with the programme name and the source.

package/07-testing/TESTING-STRATEGY.md

@@ -0,0 +1,95 @@
+# 07 · Testing strategy
+
+Run the smallest test that proves the change. Run the full suite once before a commit that finishes a task.
+
+---
+
+## 1. Layers, fastest first
+
+```
+1. Unit (domain logic)         ~10 ms per test    run when logic changes
+2. Composable (Vue reactivity) ~50 ms per test    run when a composable changes
+3. Component (Vue Test Utils)  ~200 ms per test   run when a component changes
+4. End-to-end (Playwright)     ~5 s per flow      key paths, before release
+```
+
+Accessibility checks (axe) run on every page at 390, 820 and 1440 px as part of the quality gates.
+
+---
+
+## 2. Tools
+
+| Tool | Use |
+|---|---|
+| Vitest | unit, composable and component tests |
+| `@vue/test-utils` | mounting components without a browser |
+| Playwright | flows (calculator, contact, 404) and screenshots for review |
+| axe-core | accessibility rules, through Playwright |
+
+---
+
+## 3. Commands
+
+```bash
+npx vitest run path/to/file.test.ts          # one file
+npx vitest run path/to/folder/               # one folder
+npx vitest run -t "savings"                  # by test name
+npx vitest run --reporter=dot                # short output
+npx vitest run                               # full suite, before a finishing commit
+```
+
+---
+
+## 4. Naming
+
+```ts
+// good: what is tested and what is expected
+it('calculates savings with 30% self-consumption', () => { … })
+
+// poor: says nothing about what breaks
+it('works', () => { … })
+```
+
+---
+
+## 5. Test file shape
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { calcSavings } from './residential'
+
+describe('calcSavings', () => {
+  it('returns zero savings for zero consumption', () => {
+    expect(calcSavings({ kwhMonth: 0, panelKw: 5, tariff: 0.18 })).toBe(0)
+  })
+
+  it('caps savings at the full bill', () => {
+    const r = calcSavings({ kwhMonth: 100, panelKw: 20, tariff: 0.18 })
+    expect(r.savingsPct).toBeLessThanOrEqual(100)
+  })
+})
+```
+
+Each test file runs alone, without a global setup that the test depends on.
+
+---
+
+## 6. Coverage expectations
+
+| Layer | Expectation |
+|---|---|
+| `domain/` | high; every branch of business rules |
+| `composables/` | main paths and error paths |
+| `components/ui/` | critical interactions only |
+| `pages/` | smoke test: renders, has one `h1`, no console errors |
+
+Do not unit-test static data, copy or CSS. Copy is checked by the locale parity gate; CSS by the visual review in the sandbox.
+
+---
+
+## 7. Token-efficient testing for agents
+
+1. Before editing, know which test covers the file.
+2. After editing, run that test with `--reporter=dot`.
+3. Widen the scope only if shared logic changed.
+4. Run the full suite once at the end of the task.

package/08-token-optimization/TOKEN-STRATEGY.md

@@ -0,0 +1,100 @@
+# 08 · Token and context optimisation
+
+Goal: an agent reads what the task needs and nothing else, and does not repeat work.
+
+---
+
+## 1. Map before reading
+
+Find the layer of the task first, then read only the files on its call chain:
+
+```
+task → layer → files of the layer → direct dependencies only
+```
+
+Reading order, from general to specific:
+
+1. `ds7/ALL.md` (standard rules), then the project section of the root `ALL.md`, below the AI-ALL packs block (project rules and decisions).
+3. `docs/ARCHITECTURE.md` (layer map).
+4. `app/data/<relevant>` if the task concerns data.
+5. `app/domain/<module>` if the task changes business logic.
+6. `app/composables/<name>` if a composable is involved.
+7. `app/components/<name>` if a component is changed.
+8. `app/pages/<name>` if a page is changed.
+
+Do not read all of `app/components/` or all of `app/data/`.
+
+---
+
+## 2. Project graph
+
+Keep a short graph in `docs/ARCHITECTURE.md`, one line per dependency, so the agent can find callers without searching:
+
+```
+pages/index.vue       → Hero, Systems, Equipment, Faq
+composables/usePageSeo → useHead, all pages
+data/catalog.ts       → ProductCard, Equipment
+```
+
+Update it when a dependency changes.
+
+---
+
+## 3. Working rules
+
+**Before the task**
+1. Read `ds7/ALL.md` and the project section of the root `ALL.md`.
+2. Find the layer in `docs/ARCHITECTURE.md`.
+3. Read only the files on the call chain.
+
+**During the task**
+4. After each change, run one targeted test.
+5. Do not start background processes unless needed.
+6. Use `--reporter=dot` for short test output.
+
+**At the end**
+7. Run the full suite once.
+8. Record decisions in `docs/DECISIONS.md`, not in the chat.
+9. Commit only what is verified.
+
+---
+
+## 4. File summaries
+
+Each non-trivial file starts with one or two lines describing it. An agent can read the first line to decide whether to open the file:
+
+```ts
+// Residential savings calculator. Input: monthly kWh, panel kW, tariff €/kWh. Output: SavingsResult.
+```
+
+```vue
+<!--
+  UiProductCard — product card molecule.
+  Modifiers: -top (highlight), -new (ribbon), -compact (slim).
+-->
+```
+
+---
+
+## 5. Budget guide
+
+| File | Reading strategy |
+|---|---|
+| `ds7/ALL.md` | whole file, always |
+| Project section of root `ALL.md` | whole section, always |
+| `docs/ARCHITECTURE.md` | the section that matches the layer |
+| `app/data/*.ts` | only when the task concerns data |
+| `app/domain/*.ts` | only when business logic changes |
+| `app/components/ui/*.vue` | only the file being changed |
+| `i18n/locales/*.ts` | only when keys are added |
+| `ds7/**/*.md` | on demand, one section |
+
+---
+
+## 6. Useful commands
+
+```bash
+grep -rl "useModal" app/ --include="*.vue"          # who uses a composable
+npx vitest run path/to/file.test.ts --reporter=dot   # one test, minimal output
+git diff --name-only HEAD                            # what changed
+```