@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/investor-materials/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: investor-materials
+description: Drafts startup fundraising documents, namely a pitch deck outline, a one-page investor summary and the recurring investor update, built around a clear narrative, the few metrics investors judge a company on, a specific ask and use of funds. Use when a founder is preparing to raise a seed or Series A round, writing to existing investors about progress, or wants a deck or one-pager reviewed for gaps and common fundraising mistakes.
+license: MIT
+compatibility: Any Agent Skills host. No tools required; uses the metrics and documents the founder provides.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+# Investor materials
+
+Help a founder tell a true, specific story that makes an investor want the next meeting. You draft structure and words; the founder owns every number and claim.
+
+## 0. Pick the document and collect facts
+
+Ask which of these is needed (often several):
+
+| Document | Purpose | Length |
+|---|---|---|
+| Pitch deck | Get and run the meeting | 10-15 slides plus appendix |
+| One-pager | Cold or warm intro, forwardable | One page |
+| Investor update | Keep current investors informed and helpful | One screen of email, sent on a fixed cadence |
+
+Collect before writing, and ask for anything missing:
+
+1. What the company does in one sentence, for whom, and why now.
+2. Stage, amount raised so far, the round being raised (amount, instrument such as a SAFE or priced round), and any committed investors.
+3. Real metrics with dates: revenue or MRR, growth rate, customers or users, retention, gross margin, burn and runway.
+4. Team: founders and why they are the right people.
+5. Target investors (stage, sector, geography).
+
+**Stop and ask** rather than fill a gap with an invented or rounded-up number. If a metric is weak, the narrative must deal with it honestly, not hide it.
+
+## 1. Narrative first
+
+Write the story in five sentences before any slide:
+
+1. The problem, for a specific customer, with evidence it hurts.
+2. The solution and what is different about it.
+3. Proof it is working (traction, the best single metric).
+4. Why this becomes big (market and business model).
+5. Why this team, and what this money achieves.
+
+Every slide must support one of these sentences. Cut slides that do not.
+
+## 2. Pitch deck outline
+
+Use this order unless the founder's strongest point should come earlier (often traction):
+
+1. **Title**: company, one-line description, contact.
+2. **Problem**: who has it, how they cope today, what it costs them.
+3. **Solution**: the product and the key insight. Show it (screenshot or demo flow).
+4. **Why now**: what changed (technology, regulation, behaviour, cost).
+5. **Traction**: one chart of the best metric over time, plus two or three supporting numbers.
+6. **Market**: bottom-up size (number of customers times price), not only a top-down headline figure. See the `market-research` skill for sizing.
+7. **Business model**: how you charge, price points, unit economics if known.
+8. **Competition**: honest map of alternatives, including "do nothing" and spreadsheets, and why customers pick you.
+9. **Go-to-market**: how customers are acquired today and how that scales.
+10. **Team**: relevant experience, not job-title lists.
+11. **The ask**: amount, instrument, what it funds, milestones it reaches and how many months of runway.
+12. **Appendix**: detailed financials, cohort data, product detail, for questions.
+
+Slide-writing rules: one message per slide, written as the slide headline ("Revenue grew 3x in 6 months", not "Traction"); numbers with dates and definitions; readable at a glance.
+
+Detailed slide prompts and a one-pager and update template are in `references/templates.md`. Read it when drafting the document itself.
+
+## 3. Metrics that matter
+
+Choose the ones that fit the business model and define each one:
+
+- **SaaS / subscription**: MRR or ARR, month-on-month growth, net revenue retention, logo churn, CAC payback, gross margin.
+- **Marketplace**: GMV, take rate, net revenue, repeat purchase rate, liquidity on both sides.
+- **Consumer**: active users (define active), retention cohorts, engagement frequency, organic share of acquisition.
+- **Fintech / payments**: total payment volume, revenue as a share of volume, loss and fraud rates, licences held.
+- **All**: burn, runway in months, revenue or usage concentration in top customers.
+
+Say "revenue" only for recognised revenue. Label bookings, pilots, letters of intent and GMV as what they are.
+
+## 4. The ask
+
+- State an exact amount or a narrow range, the instrument and the terms already agreed (for example a valuation cap on a SAFE).
+- Use of funds as three to five buckets with percentages that sum to 100.
+- Tie the money to milestones that make the next round possible, and the runway it buys.
+
+## 5. Investor update
+
+Send on a fixed cadence (monthly or quarterly), short, same structure every time:
+
+1. Headline: one-line summary of the period.
+2. Key metrics table, same metrics each time, with change versus last period.
+3. Wins.
+4. Challenges, stated plainly, with what you are doing about them.
+5. Asks: specific introductions, hires or advice.
+6. Cash and runway.
+
+Never skip bad months; consistency builds trust.
+
+## Common mistakes to flag when reviewing
+
+- No clear ask, or an ask with no milestones.
+- Top-down market size only ("1% of a $50B market").
+- Vanity metrics (downloads, sign-ups) without retention or revenue.
+- Undefined or cherry-picked metrics, or charts without axes and dates.
+- "No competitors".
+- Too much text; slides that need the founder to explain them.
+- Financial projections presented as facts.
+- Inconsistent numbers between deck, one-pager and data room.
+
+## Rules
+
+- Never invent, inflate or round up traction, revenue, customers, logos or committed investors. Misrepresenting facts to investors can be fraud.
+- Do not give legal, tax or securities advice; for instruments, terms and fundraising rules in the founder's jurisdiction, tell them to confirm with a lawyer.
+- Keep confidential figures out of anything the founder says will be shared publicly.
+
+## Output
+
+Deliver the requested document(s) in Markdown, followed by:
+
+```
+## Gaps and questions
+- <missing metric or claim that needs a source>
+## Review notes
+- <mistakes from the list above that apply, with the fix>
+```

package/skills/investor-materials/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "We're raising a $1.5M seed round. Help me outline the pitch deck.",
+    "Write our monthly update to investors: MRR is up 12%, we lost a big customer and runway is 14 months",
+    "Turn these notes into a one-page summary I can send to angel investors",
+    "Review my Series A deck and tell me what VCs will push back on",
+    "What metrics should a B2B SaaS startup put on the traction slide, and how do I phrase the ask?"
+  ],
+  "should_not_trigger": [
+    "Estimate TAM, SAM and SOM for a pharmacy inventory app in Nigeria with sources",
+    "Plan a launch campaign with a budget split across paid social and email",
+    "Write a long-form blog post on lessons from our first year as a startup",
+    "Define the voice and tone guidelines for our company's website copy",
+    "Prepare release notes for version 2.0 of our CLI"
+  ]
+}

package/skills/investor-materials/references/templates.md

@@ -0,0 +1,74 @@
+# Investor materials: templates
+
+Read this when drafting. Replace every `<...>` with the founder's facts; leave a visible `TODO` where a fact is missing instead of guessing.
+
+## Pitch deck slide prompts
+
+| Slide | Headline pattern | Body | Check |
+|---|---|---|---|
+| Title | `<Company>: <what it does for whom>` | Logo, contact, round | Understandable without speaking |
+| Problem | `<Customer> loses <cost> because <cause>` | Quote or data point, current workaround | Specific customer, not "everyone" |
+| Solution | `<Product> lets <customer> <outcome>` | Screenshot or 3-step flow | Shows the product |
+| Why now | `<Change> makes this possible now` | 1-3 changes with dates | Real change, not hype |
+| Traction | `<Metric> grew <x> in <period>` | One chart, 2-3 supporting numbers | Dates, definitions, axes |
+| Market | `<N> <customers> x <price> = <size>` | Bottom-up arithmetic, sources | Shows the calculation |
+| Business model | `We earn <price> per <unit>` | Pricing, margin, unit economics | Matches traction numbers |
+| Competition | `Customers choose us because <reason>` | Matrix or table of alternatives | Includes "do nothing" |
+| Go-to-market | `We acquire customers through <channel>` | Current CAC or conversion if known | Evidence, not plans only |
+| Team | `<Team> has done <relevant thing>` | Founders, key hires, advisers | Relevance to this problem |
+| Ask | `Raising <amount> to reach <milestone>` | Instrument, use of funds, runway | Percentages sum to 100 |
+
+## One-pager
+
+```
+# <Company>: <one-line description>
+<Website> | <Founder name, email> | Raising <amount> <instrument>
+
+**Problem.** <2 sentences>
+**Solution.** <2 sentences>
+**Traction.** <best metric with date>; <2 supporting numbers>
+**Market.** <bottom-up size, one line of arithmetic>
+**Business model.** <how you charge, price>
+**Competition.** <alternatives and why customers pick you>
+**Team.** <founders, one line each>
+**The ask.** <amount>, <use of funds in 3 buckets>, reaching <milestone> with <n> months runway
+```
+
+## Investor update (email)
+
+```
+Subject: <Company> update, <Month Year>: <headline>
+
+Hi all,
+
+TL;DR: <one line>
+
+| Metric | This period | Last period | Change |
+|---|---|---|---|
+| <MRR> | | | |
+| <Active customers> | | | |
+| <Burn / month> | | | |
+| Runway (months) | | | |
+
+Wins
+- <...>
+
+Challenges
+- <problem>, what we are doing: <action>
+
+Asks
+- <specific intro: name or profile, why>
+
+Thanks,
+<Founder>
+```
+
+## Review checklist
+
+- [ ] Narrative fits in five sentences and every slide supports one.
+- [ ] Each metric is defined and dated, and matches across documents.
+- [ ] The ask has an amount, instrument, use of funds and milestone.
+- [ ] Market size includes a bottom-up calculation.
+- [ ] Competition slide names real alternatives.
+- [ ] Projections are labelled as projections.
+- [ ] No claim without a source the founder can show.

package/skills/invoicing-and-tax/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: invoicing-and-tax
+description: Guides software teams through issuing legally usable invoices and charging sales tax, VAT or GST correctly, covering required invoice fields and sequential numbering, choosing a tax calculation service or merchant of record over hand-rolled rate tables, registration thresholds and nexus at a high level, reverse charge for B2B, tax-inclusive versus exclusive pricing, line-level rounding, and national e-invoicing mandates such as Peppol, KSeF and Factur-X, with a firm handoff to a qualified accountant for anything that is a tax position. Use when building or fixing invoice generation, adding VAT or sales tax to checkout, deciding whether to integrate Avalara, Stripe Tax or a merchant of record, or preparing for an e-invoicing deadline in a country you sell into.
+license: MIT
+compatibility: Any Agent Skills host. Provider-neutral. Tax thresholds, rates and mandate dates change often; the agent must check official sources before quoting them.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Invoicing and tax
+
+Produce invoices that a tax authority would accept and tax amounts a customer can re-add by hand, while keeping every tax *decision* with a qualified person. You build the machinery; an accountant or tax adviser decides where you are registered, what is taxable and at which rate.
+
+## What this skill does not cover
+
+- It is not tax or legal advice. It does not decide whether a product is taxable, whether you have nexus or a VAT obligation somewhere, which rate or exemption applies, or how to file returns.
+- It does not cover payroll tax, income or corporate tax, customs duties (see `customs-trade-compliance` if installed), or revenue recognition policy.
+- Thresholds, rates and deadlines in this skill and its references are orientation only and may be out of date. Before relying on one, check the tax authority's own site and say which source and date you used.
+
+**Stop and ask for a qualified accountant or tax adviser** before: registering or not registering somewhere, choosing a product tax code or exemption, applying reverse charge or zero rating, issuing invoices in a new country, changing how past invoices were taxed, or answering a customer's tax dispute.
+
+## Ground rules
+
+1. **Never hand-roll rate tables** for more than a single jurisdiction you are registered in. Rates, product taxability and US local jurisdictions change constantly. Use a tax engine (Avalara AvaTax, Stripe Tax, Anrok, TaxJar, Quaderno and similar) or a merchant of record (Paddle, Lemon Squeezy and similar), which becomes the seller and takes on the tax liability.
+2. **Store the tax decision on the invoice line**, not just the result: jurisdiction, rate, tax code, taxable amount, tax amount, and the engine's transaction or calculation ID. You must be able to explain an old invoice after rates change.
+3. **Invoices are immutable once issued.** Correct with a credit note that references the original and reverses its tax in proportion. Never edit, renumber or delete.
+4. **Numbering**: one sequential series per legal entity (and per series type if the jurisdiction allows), assigned at finalisation inside a transaction, no reuse. Many VAT regimes require a unique sequential number; gaps need an explanation.
+5. **Money is integer minor units plus currency.** Round with the method the jurisdiction specifies, at the level it specifies (line or invoice total). Details in `references/rounding.md`.
+6. **Customer location evidence** is stored with each sale (billing address, IP country, payment method country, VAT ID validation result) because B2C digital sales in many regimes are taxed where the customer is.
+7. **Validate B2B tax IDs** before applying reverse charge: EU VAT numbers via the EU [VIES](https://ec.europa.eu/taxation_customs/vies/) service, UK VAT numbers via HMRC's [check a UK VAT number](https://www.gov.uk/check-uk-vat-number) service, and store the check result and timestamp.
+
+## Workflow
+
+1. **Inventory.** Search the codebase for invoice generation, PDF templates, numbering, tax calculation, the checkout price display, and credit notes. List which legal entity issues invoices and where customers are.
+2. **Ask the user for the tax position** (from their accountant): where they are registered, products' tax codes, whether prices are tax-inclusive per market, B2B vs B2C mix. If unknown, stop; don't guess.
+3. **Pick the approach** with the table below and confirm with the user.
+4. **Required fields.** Check the invoice against the jurisdiction's list. EU baseline is in `references/invoice-fields.md`; others vary.
+5. **Integrate the engine**: calculate at quote/checkout with the full address and tax IDs, commit (record) the transaction when the invoice is finalised, and void or refund it in the engine when you issue a credit note. Calculate-only calls without commits leave the engine's reports empty.
+6. **Prices display**: show tax-inclusive prices to consumers where that is the norm (EU, UK, Australia) and tax-exclusive plus tax at checkout where that is the norm (US). Decide per market with the user.
+7. **E-invoicing**: check whether any country you invoice in mandates structured e-invoices for your customer type; see `references/e-invoicing.md`. Usually this means an accredited provider or Peppol access point, not building the transmission yourself.
+8. **Test** with fixtures: one domestic B2C, one domestic B2B, one cross-border B2B with a valid tax ID (reverse charge), one with an invalid tax ID, one US address in a taxing state, a refund producing a credit note, a multi-line invoice that stresses rounding.
+
+## Choose the approach
+
+| Situation | Usually |
+|---|---|
+| One country, registered there, simple products | Engine is optional; a reviewed, tested rate config for that one country is acceptable |
+| Selling to consumers in many countries, small team | Merchant of record, or a tax engine plus registrations your adviser sets up |
+| US sales across states | Tax engine; economic nexus thresholds differ by state |
+| Marketplace or platform paying out to sellers | Stop and ask; marketplace facilitator rules may make you the collector |
+| Large B2B, ERP-driven | Tax engine integrated with the ERP; invoices issued from one system only |
+
+## Thresholds at a high level
+
+Registration duty depends on where you are established, what you sell and to whom. Orientation only, all to be verified with the authority before use:
+
+- **US sales tax**: since [*South Dakota v. Wayfair*](https://www.supremecourt.gov/opinions/17pdf/17-494_j4el.pdf) (2018), states can require remote sellers to collect once they cross an economic nexus threshold. The South Dakota law upheld there used more than 100,000 USD of sales or 200 transactions a year into the state; each state sets its own figures and tests, so check that state's revenue department. Taxability of SaaS and digital goods differs by state.
+- **EU VAT**: a seller established in only one EU member state has a 10,000 EUR EU-wide annual threshold (current and preceding calendar year) for cross-border B2C telecoms, broadcasting and electronic services and intra-EU distance sales of goods; above it, VAT is due in the customer's country, usually declared via the [One Stop Shop](https://vat-one-stop-shop.ec.europa.eu/one-stop-shop_en) (OSS). Sellers not established in the EU have no threshold for B2C services and use the non-Union OSS.
+- **UK VAT**: [registration threshold](https://www.gov.uk/register-for-vat) 90,000 GBP of taxable turnover over the last 12 months, or expected within the next 30 days, for UK-established businesses; [non-established taxable persons](https://www.gov.uk/government/publications/vat-notice-7001-should-i-be-registered-for-vat/vat-notice-7001-should-i-be-registered-for-vat) must register on their first UK taxable supply, with no threshold.
+- **Others** (Australia, Canada, India, Norway, Switzerland, Singapore, many more) have their own regimes for foreign digital sellers. Look them up per country.
+
+## Never
+
+- Never present computed tax as advice, or tell a user they don't need to register somewhere.
+- Never silently apply 0% because a tax ID field is non-empty; validate it.
+- Never recalculate tax on an issued invoice with today's rates.
+- Never compute tax on floats or round the total separately from lines without a defined rule.
+- Never generate invoices from two systems for the same sale (for example, both the payment provider and your app).
+
+## Report format
+
+When reviewing or designing, return:
+
+```
+Issuing entity and series: <entity, numbering scheme>
+Approach: <engine | merchant of record | single-country config>
+Markets checked: <country: B2B/B2C, registered?, inclusive/exclusive, e-invoice mandate?, source + date checked>
+Field gaps: <missing required fields per market>
+Rounding rule: <method, level>
+Needs accountant decision: <list>
+```

package/skills/invoicing-and-tax/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Our generated PDF invoices are missing the customer's VAT number and the reverse charge note for EU business customers",
+    "Should we integrate Avalara or Stripe Tax, or switch to a merchant of record like Paddle for selling SaaS worldwide?",
+    "Belgium now requires Peppol e-invoices for B2B; what do we need to change in our invoicing system?",
+    "Tax on our invoices is off by a cent compared with the total; should VAT be rounded per line or per invoice?",
+    "We start selling to US customers in several states. How do we figure out where we need to collect sales tax?",
+    "Make our invoice numbers sequential and gap-free per legal entity, they currently use random IDs"
+  ],
+  "should_not_trigger": [
+    "Implement mid-cycle proration when a customer upgrades from the monthly to the annual plan",
+    "Classify our product under the right HS code for importing into the EU",
+    "Sync invoices from our app into Xero with the right account codes",
+    "Check our payroll setup for the right employer tax withholding",
+    "Review this pull request that changes how invoice totals are calculated"
+  ]
+}

package/skills/invoicing-and-tax/references/e-invoicing.md

@@ -0,0 +1,24 @@
+# E-invoicing mandates
+
+An e-invoice here means a structured, machine-readable invoice (XML such as UBL or CII), often sent through a network or a government platform. A PDF by email is not one.
+
+**Dates below were checked against the national authorities' own pages in October 2026 (linked in the table) and change often. Check the authority again before acting, and record the source and date you used.**
+
+| Country | Status as reported | Format / channel |
+|---|---|---|
+| Italy ([Agenzia delle Entrate](https://www.agenziaentrate.gov.it/portale/web/guest/schede/comunicazioni/fatture-e-corrispettivi/faq-fe/risposte-alle-domande-piu-frequenti-categoria/emissione-delle-fatture-elettroniche-imprese)) | Domestic B2B and B2C via SDI since 1 Jan 2019 (consumers can get a paper or PDF copy) | FatturaPA XML through Sistema di Interscambio |
+| Germany ([BMF FAQ](https://www.bundesfinanzministerium.de/Content/DE/FAQ/e-rechnung.html)) | Domestic B2B: all businesses must be able to receive e-invoices since 1 Jan 2025. Other invoice types allowed until 31 Dec 2026, or until 31 Dec 2027 for issuers with prior-year turnover up to 800,000 EUR. So issuing is mandatory from 1 Jan 2027 for larger issuers and from 1 Jan 2028 for all | EN 16931 formats such as XRechnung or ZUGFeRD/Factur-X |
+| Belgium ([einvoice.belgium.be](https://einvoice.belgium.be/en/article/structured-electronic-invoices-between-companies-are-compulsory-2026)) | Structured e-invoices mandatory between Belgian VAT-registered businesses since 1 Jan 2026; not for consumers; cross-border out of scope until ViDA | Peppol network, Peppol BIS as the reference format |
+| Poland ([ksef.podatki.gov.pl](https://ksef.podatki.gov.pl/informacje-ogolne-ksef-20/zakres-obowiazkowego-ksef/)) | Receiving via KSeF mandatory for all from 1 Feb 2026; issuing from 1 Feb 2026 for taxpayers with 2024 sales over 200m PLN, from 1 Apr 2026 for others; those invoicing at most 10,000 PLN gross a month have until the end of 2026 | National KSeF platform, structured XML |
+| France ([impots.gouv.fr](https://www.impots.gouv.fr/facturation-electronique-et-plateformes-agreees)) | Receiving for all businesses, and issuing plus e-reporting for large and mid-size (GE, ETI), from 1 Sep 2026; issuing for SMEs and micro-businesses from 1 Sep 2027 | Via approved platforms (plateformes agréées); check DGFiP's specifications for the accepted formats |
+| EU-wide ([ViDA](https://taxation-customs.ec.europa.eu/taxation/vat/vat-digital-age-vida_en)) | VAT in the Digital Age package adopted 11 Mar 2025; mandatory e-invoicing with digital reporting for intra-EU B2B transactions from 1 Jul 2030; national systems to align by 1 Jan 2035 | EN 16931 baseline |
+
+Outside the EU, mandates exist in many countries (for example India, Mexico, Saudi Arabia, Malaysia, Türkiye, Brazil) with their own schemas and clearance steps.
+
+## What it means for a software team
+
+1. List where your customers are and which are businesses. Mandates mostly target domestic B2B first.
+2. Most teams connect to an accredited provider or a Peppol access point rather than implementing the network or government API directly.
+3. Your invoice data must already contain everything the format needs: buyer tax ID, structured address, per-line tax category codes, unit codes, payment means. Gaps here are the usual blocker.
+4. Archive the structured invoice as sent, for the retention period the country requires.
+5. Receiving is also a mandate in some countries; check whether you must accept supplier e-invoices in your accounts payable process.

package/skills/invoicing-and-tax/references/invoice-fields.md

@@ -0,0 +1,38 @@
+# Invoice fields
+
+## EU VAT invoice baseline
+
+The EU VAT Directive ([2006/112/EC](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:02006L0112-20250414), Article 226) lists what a full VAT invoice must show. Member states implement it in national law and may add rules, so check the country's guidance too. Summary of the list:
+
+1. Date of issue
+2. Sequential number that uniquely identifies the invoice
+3. Supplier's VAT identification number
+4. Customer's VAT identification number where the customer is liable for the tax (reverse charge) or for intra-EU supplies of goods
+5. Full name and address of supplier and customer
+6. Quantity and nature of goods, or extent and nature of services
+7. Date of supply or payment, if different from the issue date
+8. Taxable amount per rate or exemption, unit price excluding VAT, and any discounts not included in the unit price
+9. VAT rate applied
+10. VAT amount payable
+11. Where exempt or reverse charged, a reference to the provision or the wording such as "Reverse charge"
+12. Other mentions where they apply: "Self-billing", "Cash accounting", the margin scheme wording, new means of transport details, a tax representative's VAT number, name and address
+
+The invoice may be in any currency, but the VAT payable must also be expressed in the national currency of the member state (Article 230).
+
+Simplified invoices with fewer fields (Article 226b) are allowed for low amounts; the limit is set nationally within the Directive's rules.
+
+## Fields that help everywhere
+
+- Legal entity name, registered address, company number where local law requires it
+- Payment terms, due date, how to pay
+- Purchase order number when the customer gives one
+- Service period for subscriptions (`1 Apr 2026 – 30 Apr 2026`)
+- For credit notes: "Credit note", own number, and the original invoice number and date
+
+## United States
+
+There is no federal invoice format. States set what a sales tax invoice or receipt must show; the tax amount is commonly shown separately. A tax engine's documentation usually lists state requirements.
+
+## Elsewhere
+
+Many countries (for example Mexico CFDI, India GST e-invoicing, Brazil NF-e, Saudi Arabia, Türkiye) require government-validated electronic invoices with specific schemas and IDs. Don't generate a PDF and assume it is valid there; use an accredited provider and check the authority's rules.

package/skills/invoicing-and-tax/references/rounding.md

@@ -0,0 +1,26 @@
+# Tax rounding
+
+## Pick and document
+
+- **Level**: per line (compute tax per line, round, sum) or per invoice (sum taxable amounts per rate, compute tax once, round). Some authorities specify one. EN 16931 e-invoices compute VAT per VAT category and rate: the category taxable amount is the sum of line net amounts plus charges minus allowances ([BR-S-08](https://docs.peppol.eu/poacc/billing/3.0/rules/ubl-tc434/BR-S-08/) for standard rate), and the category tax amount must equal taxable amount × rate, rounded to two decimals ([BR-CO-17](https://docs.peppol.eu/poacc/billing/3.0/rules/ubl-tc434/BR-CO-17/)). Per-line-rounded tax can fail that check; if you issue e-invoices, use per-invoice-per-rate. Ask the accountant which applies.
+- **Method**: half-up is the usual commercial default; some regimes specify otherwise. Use a decimal type, never binary floats.
+- **Inclusive prices**: tax = gross × rate ÷ (1 + rate). Round tax, then net = gross − tax, so net + tax always equals the advertised gross.
+
+## Example of the difference
+
+Three lines of 0.99 (minor units: 99) at 20% VAT, tax-exclusive:
+
+```
+per line:    round(99 * 0.20) = round(19.8) = 20 per line → 60 total
+per invoice: round(297 * 0.20) = round(59.4) = 59
+```
+
+A one-unit difference per invoice adds up and makes tax returns disagree with ledgers. Whatever you choose, the tax engine, your invoice PDF and the accounting system must use the same rule.
+
+## Tests worth having
+
+- Many small lines at a rate that produces .5 fractions
+- A tax-inclusive price where `gross / (1 + rate)` has a repeating decimal
+- Mixed rates on one invoice (summed per rate)
+- A credit note for one line of a multi-line invoice: its tax must equal the tax originally charged on that line
+- Zero-decimal (JPY) and three-decimal (KWD) currencies

package/skills/ios-platform-features/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: ios-platform-features
+description: Adopts recent Apple platform APIs in an existing app without dropping older OS versions, covering the Liquid Glass design (glassEffect, GlassEffectContainer, glass button styles, UIGlassEffect, UIDesignRequiresCompatibility), the on-device Foundation Models framework with SystemLanguageModel availability, LanguageModelSession, @Generable guided generation and the Tool protocol, #available checks with real fallbacks, and layered Icon Composer app icons. Use when an iOS, iPadOS or macOS app is moving to the iOS 26 or later SDK, adding an Apple Intelligence text feature that runs on device, gating a new API behind an availability check, or replacing an AppIcon asset catalog with an .icon file.
+license: MIT
+compatibility: Any Agent Skills host. Needs Xcode 26 or later with the matching SDKs; Foundation Models features need an Apple Intelligence capable device or Mac to test on. APIs change between SDK releases, so every name must be checked against developer.apple.com for the SDK in use.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/requires: "xcodebuild"
+  kete-loom/owner: "Kete-org"
+---
+
+# iOS platform features
+
+Bring an app onto Apple's newest APIs while it keeps working on every OS version it still supports. General Swift style lives in the Swift and SwiftUI skills; this skill is about new platform surfaces and gating them.
+
+## 0. Before you start
+
+1. Read the deployment target (target, General, Minimum Deployments, or `IPHONEOS_DEPLOYMENT_TARGET`) and the Xcode and SDK version (`xcodebuild -version`, `xcodebuild -showsdks`).
+2. **Verify every API against Apple's documentation for that SDK before you write it.** Open the symbol page on developer.apple.com and read its availability line. Apple renames and deprecates these APIs between major releases (for example, the iOS 27 SDK adds `LanguageModelError`, `SystemLanguageModel.Error` and `LanguageModelSession.Error` alongside the iOS 26 `LanguageModelSession.GenerationError`). If you cannot confirm a name, say so and do not guess.
+3. Build once and run the tests before changing anything. Record warnings.
+
+## 1. Availability rules (apply to every feature below)
+
+- Gate code with `if #available(iOS 26, *) { ... } else { ... }` and types or members with `@available(iOS 26, *)`. Use the matching macOS, visionOS or watchOS versions for those targets.
+- Every gated path has a real fallback that a user on the older OS can use. Hiding a button is a fallback only if the feature is optional.
+- Keep gated code in small wrappers (one view modifier, one service type), not scattered `#available` checks.
+- Test both branches: a simulator on the newest OS and one on the oldest supported OS.
+- Raising the deployment target is a product decision. **Stop and ask the user** before doing it to avoid writing a fallback.
+
+## 2. Liquid Glass
+
+Building with the iOS 26 SDK gives standard components (navigation bars, tab bars, toolbars, sheets, buttons, sliders) the new material automatically.
+
+1. Rebuild and walk every screen on an iOS 26+ simulator. Look for custom backgrounds on bars, toolbars, split views and sheets that fight the system material, and remove them first.
+2. For custom controls, prefer the system button styles: SwiftUI `.buttonStyle(.glass)` and `.buttonStyle(.glassProminent)`; UIKit `UIButton.Configuration.glass()`, `.prominentGlass()`, `.clearGlass()`, `.prominentClearGlass()`.
+3. Only then use the effect directly: `.glassEffect()` (default `.regular` in a capsule), `.glassEffect(.regular.tint(.orange).interactive(), in: .rect(cornerRadius: 16))`. Apply it after the modifiers that set the view's appearance. UIKit uses `UIGlassEffect` in a `UIVisualEffectView`; AppKit uses `NSGlassEffectView`.
+4. Group nearby glass views in `GlassEffectContainer(spacing:)` for performance and morphing; use `glassEffectID(_:in:)` with a `@Namespace` for morph transitions and `glassEffectUnion(id:namespace:)` to merge shapes at rest.
+5. Use glass sparingly: controls and navigation, never content such as list rows or cards of text.
+6. Content scrolling under a custom bar: use `safeAreaBar(edge:...)` (SwiftUI) or `UIScrollEdgeElementContainerInteraction` (UIKit) to get the scroll edge effect.
+7. Wrap custom glass in one modifier that falls back on older OS versions:
+
+```swift
+extension View {
+    @ViewBuilder func appGlass() -> some View {
+        if #available(iOS 26, *) { self.glassEffect() }
+        else { self.background(.ultraThinMaterial, in: Capsule()) }
+    }
+}
+```
+
+8. Check legibility with Reduce Transparency, Increase Contrast and Reduce Motion on, in light and dark mode.
+9. The `UIDesignRequiresCompatibility` Info.plist key keeps the pre-Liquid Glass look only for builds made with the Xcode 26 SDKs. Apple has said builds made with the Xcode 27 SDKs ignore it, whatever the deployment target. Do not offer it as a fix on Xcode 27 or later; tell the user the redesign cannot be postponed past that SDK.
+
+## 3. Foundation Models (on-device language model)
+
+Read `references/foundation-models.md` before writing code; it has the session, guided generation and tool patterns.
+
+1. Decide whether the task fits a small on-device model: summarising, extracting fields, classifying, rewriting or tagging the user's own content. It is not a source of world knowledge or facts. **Stop and ask** if the feature needs accurate facts, long documents or heavy reasoning.
+2. Check `SystemLanguageModel.default.availability` every time before offering the feature, and handle each `.unavailable` reason: `.deviceNotEligible` (hide the feature), `.appleIntelligenceNotEnabled` (explain how to turn it on), `.modelNotReady` (try later; the model may be downloading).
+3. Prefer guided generation (`@Generable` types with `@Guide` constraints) over parsing free text.
+4. Give the model app data through a `Tool` only when it must decide what to fetch; otherwise put the data in the prompt.
+5. Handle errors: context window exceeded, guardrail violation, unsupported language or locale, and concurrent requests on one session. Use the error type your SDK documents.
+6. Keep the user in control: show generated text as a draft they can edit or discard, never act on it automatically.
+7. If the project builds with the iOS 27 SDK or later, read Apple's "Foundation Models updates" page first (it lists the `LanguageModel` protocol for other models, `PrivateCloudComputeLanguageModel`, image input, `LanguageModelSession.DynamicProfile` and the new error types); do not assume iOS 26 signatures still apply. `PrivateCloudComputeLanguageModel` and server models are not on-device: **stop and ask** before using them, and describe the feature accordingly.
+
+## 4. App icons with Icon Composer
+
+1. Open Icon Composer from Xcode (Xcode, Open Developer Tool, Icon Composer). Import layers as SVG (PNG for unsupported features), up to four groups, back to front. Leave out blur, shadow, background and the mask; Icon Composer and the system add them.
+2. Check the default, dark and mono (clear and tinted) appearances in the canvas.
+3. Add the `.icon` file to the app target and make the App Icon name in the target's General tab match the file name without extension (usually `AppIcon`).
+4. When the target has an `.icon` file, Xcode uses it instead of an `AppIcon` asset set of the same name and generates the images older OS versions show; a different icon per OS version is not supported. Check the icon on the oldest supported OS, and **ask the user** before deleting the old asset set.
+5. tvOS and visionOS targets still use asset catalogs.
+
+## 5. Verify
+
+1. Build for every platform the app supports and fix new availability warnings.
+2. Run on the newest and the oldest supported OS. Exercise each new feature and its fallback.
+3. Foundation Models: test on a real eligible device, with Apple Intelligence off, and with an unsupported language.
+4. Run the test suite. Add a test for each fallback path you can reach (for example, a fake model service behind a protocol).
+
+## Never
+
+- Never call an API without checking it on developer.apple.com for the SDK in use.
+- Never ship a Foundation Models feature without a path for every unavailable reason.
+- Never send the user's content to a server while describing the feature as on-device.
+- Never cover text-heavy content with glass or stack glass on glass.
+- Never raise the deployment target silently.
+
+## Report back
+
+```
+SDK / deployment target: <Xcode version, SDK, min OS>
+Adopted: <feature> | <files> | <availability gate> | <fallback>
+Verified on: <OS versions and devices>, tests: <command and result>
+APIs checked against docs: <list>; could not confirm: <list>
+Open questions: <deployment target, icon fallback, design decisions>
+```

package/skills/ios-platform-features/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Add an on-device summary of the user's notes with Apple's Foundation Models framework, with a fallback when Apple Intelligence is off",
+    "We rebuilt with the iOS 26 SDK, how do we adopt Liquid Glass in our custom toolbar and keep iOS 17 working?",
+    "Replace our AppIcon asset catalog with an Icon Composer .icon file that has dark and tinted variants",
+    "Use @Generable guided generation to extract event details from an email on device",
+    "Wrap glassEffect and GlassEffectContainer in availability checks so the app still builds for iOS 18"
+  ],
+  "should_not_trigger": [
+    "Migrate our Swift package to the Swift 6 language mode and fix Sendable warnings",
+    "Our SwiftUI view keeps resetting its state when the parent redraws",
+    "Call the Claude API from our iOS app's backend to answer support questions",
+    "Write Swift Testing tests for our actor-based cache",
+    "Make our iOS app's icon buttons readable by VoiceOver and fix focus order"
+  ]
+}

package/skills/ios-platform-features/references/foundation-models.md

@@ -0,0 +1,90 @@
+# Foundation Models patterns (iOS 26 SDK)
+
+Signatures shown are the iOS 26 forms; newer SDKs add overloads (metadata, context options, dynamic profiles) and a separate error type. Re-check each symbol page for the SDK you build with.
+
+## Availability
+
+```swift
+import FoundationModels
+
+enum SummaryAvailability { case ready, hidden, needsAppleIntelligence, tryLater }
+
+func summaryAvailability() -> SummaryAvailability {
+    switch SystemLanguageModel.default.availability {
+    case .available: return .ready
+    case .unavailable(.deviceNotEligible): return .hidden
+    case .unavailable(.appleIntelligenceNotEnabled): return .needsAppleIntelligence
+    case .unavailable(.modelNotReady): return .tryLater
+    case .unavailable: return .hidden // future reasons: fail closed
+    }
+}
+```
+
+Re-check availability when the app returns to the foreground; it can change.
+
+## Session
+
+```swift
+let session = LanguageModelSession(instructions: """
+    You summarise the user's notes in two sentences. Use only the text given.
+    """)
+let response = try await session.respond(to: noteText)
+let summary = response.content
+```
+
+- A session keeps a transcript; reuse it for a multi-turn conversation, create a new one for unrelated requests.
+- One request at a time per session; check `session.isResponding` before sending another.
+- Call `session.prewarm(promptPrefix:)` when you know a request is coming (for example, when the sheet opens).
+- Stream into the UI with `for try await partial in session.streamResponse(to: prompt) { ... }`.
+
+## Guided generation
+
+```swift
+@Generable
+struct ExtractedEvent {
+    @Guide(description: "Short event title")
+    var title: String
+    @Guide(description: "Attendee first names", .count(0...10))
+    var attendees: [String]
+}
+
+let result = try await session.respond(to: emailText, generating: ExtractedEvent.self)
+let event = result.content
+```
+
+- The framework constrains decoding to the type, so you do not parse JSON yourself.
+- Keep types small and flat; each property and guide adds to the prompt.
+- Enums marked `@Generable` give you classification.
+
+## Tool calling
+
+```swift
+struct FindContacts: Tool {
+    let name = "findContacts"
+    let description = "Finds contacts whose name matches a query"
+
+    @Generable
+    struct Arguments {
+        @Guide(description: "Part of the contact's name")
+        let query: String
+    }
+
+    func call(arguments: Arguments) async throws -> [String] {
+        try await contactStore.names(matching: arguments.query) // your code, with its own permission checks
+    }
+}
+
+let session = LanguageModelSession(tools: [FindContacts()], instructions: "Help the user find contacts.")
+```
+
+- `Tool` requires `name`, `description`, an `Arguments` type (usually `@Generable`) and `call(arguments:) async throws -> Output`, where `Output` conforms to `PromptRepresentable` (a `String` or a `@Generable` type).
+- Tool definitions count against the context window; register only the tools a session needs.
+- A tool runs with the app's permissions. Check authorisation inside `call` and never let a tool perform a destructive action without the user confirming in the UI.
+
+## Errors (iOS 26 SDK)
+
+`LanguageModelSession.GenerationError` cases include `exceededContextWindowSize`, `guardrailViolation`, `unsupportedLanguageOrLocale`, `concurrentRequests`, `decodingFailure`, `assetsUnavailable`, `rateLimited`, `refusal` and `unsupportedGuide`. On context overflow, start a new session with a shorter summary of the conversation. On a guardrail violation or refusal, show a neutral message and let the user edit the input. The iOS 27 SDK adds `LanguageModelError` (model errors), `SystemLanguageModel.Error` (on-device model errors) and `LanguageModelSession.Error` (session errors); read their symbol pages for the case names before catching them.
+
+## Testing
+
+Put the model behind a small protocol (`protocol Summariser { func summarise(_: String) async throws -> String }`) so unit tests use a fake and UI tests can force each availability state. Evaluate real output on a device with a fixed set of sample inputs before shipping.