@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/go-patterns/references/concurrency.md

@@ -0,0 +1,162 @@
+# Go concurrency patterns
+
+Each pattern stops cleanly when the context is cancelled and waits for every goroutine it starts.
+
+## Fan-out with errgroup and a concurrency limit
+
+```go
+import "golang.org/x/sync/errgroup"
+
+func fetchAll(ctx context.Context, ids []string) ([]Item, error) {
+	items := make([]Item, len(ids)) // each goroutine writes its own index: no lock needed
+	g, ctx := errgroup.WithContext(ctx)
+	g.SetLimit(8)
+	for i, id := range ids {
+		g.Go(func() error {
+			it, err := fetch(ctx, id)
+			if err != nil {
+				return fmt.Errorf("fetch %s: %w", id, err)
+			}
+			items[i] = it
+			return nil
+		})
+	}
+	if err := g.Wait(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+```
+
+Since Go 1.22 each loop iteration has its own `i` and `id`, so capturing them is safe. On a module whose `go` directive is older than 1.22, copy them first (`i, id := i, id`).
+
+## Worker pool over a channel
+
+```go
+func process(ctx context.Context, jobs []Job, workers int) error {
+	in := make(chan Job)
+	g, ctx := errgroup.WithContext(ctx)
+
+	g.Go(func() error { // producer owns and closes in
+		defer close(in)
+		for _, j := range jobs {
+			select {
+			case in <- j:
+			case <-ctx.Done():
+				return ctx.Err()
+			}
+		}
+		return nil
+	})
+
+	for range workers {
+		g.Go(func() error {
+			for j := range in {
+				if err := handle(ctx, j); err != nil {
+					return err
+				}
+			}
+			return nil
+		})
+	}
+	return g.Wait()
+}
+```
+
+`for range workers` (ranging over an int) needs Go 1.22+; use `for i := 0; i < workers; i++` on older modules.
+
+## Pipeline stage that cannot leak
+
+```go
+func squares(ctx context.Context, in <-chan int) <-chan int {
+	out := make(chan int)
+	go func() {
+		defer close(out)
+		for v := range in {
+			select {
+			case out <- v * v:
+			case <-ctx.Done():
+				return
+			}
+		}
+	}()
+	return out
+}
+```
+
+The `select` on `ctx.Done()` is what prevents the leak: without it the goroutine blocks forever on `out <-` once the consumer stops reading.
+
+## First result wins (with no leak)
+
+```go
+func first(ctx context.Context, replicas []string) (Result, error) {
+	ctx, cancel := context.WithCancel(ctx)
+	defer cancel()
+	ch := make(chan Result, len(replicas)) // buffered: losers never block
+	for _, r := range replicas {
+		go func() {
+			if res, err := query(ctx, r); err == nil {
+				ch <- res
+			}
+		}()
+	}
+	select {
+	case res := <-ch:
+		return res, nil
+	case <-ctx.Done():
+		return Result{}, ctx.Err()
+	}
+}
+```
+
+If every replica fails this waits for the parent context; add a timeout or count failures if that is not acceptable.
+
+## Mutex-guarded state
+
+```go
+type Counter struct {
+	mu sync.Mutex
+	n  map[string]int // guarded by mu
+}
+
+func (c *Counter) Inc(k string) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.n == nil {
+		c.n = make(map[string]int)
+	}
+	c.n[k]++
+}
+```
+
+Methods use a pointer receiver so the mutex is never copied. `go vet` (copylocks) flags copies.
+
+## Graceful HTTP shutdown
+
+```go
+func run(ctx context.Context) error {
+	ctx, stop := signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	srv := &http.Server{Addr: ":8080", Handler: routes(), ReadHeaderTimeout: 5 * time.Second}
+	errCh := make(chan error, 1)
+	go func() { errCh <- srv.ListenAndServe() }()
+
+	select {
+	case err := <-errCh:
+		return err
+	case <-ctx.Done():
+	}
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	return srv.Shutdown(shutdownCtx)
+}
+```
+
+`ListenAndServe` returns `http.ErrServerClosed` after `Shutdown`; treat that as success if you read `errCh` afterwards. The shutdown context is deliberately new: the signal context is already cancelled.
+
+## Detecting leaks and races
+
+- `go test -race ./...` on every change that touches goroutines or shared state.
+- `go.uber.org/goleak` (`defer goleak.VerifyNone(t)` or `goleak.VerifyTestMain(m)`) catches goroutines still running at test end, if the project accepts the dependency.
+- A goroutine dump (`SIGQUIT`, or `net/http/pprof` at `/debug/pprof/goroutine?debug=2`) shows where leaked goroutines are blocked.

package/skills/go-testing/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: go-testing
+description: Writes and fixes Go tests with the standard testing package, including table-driven tests with t.Run subtests, t.Helper and t.Cleanup, httptest servers and recorders, hand-written fakes instead of mock frameworks, the race detector, native fuzzing, benchmarks and golden files. Use when adding or repairing _test.go files, making flaky Go tests deterministic, testing an HTTP handler or client in Go, or writing a Go fuzz target or benchmark.
+license: MIT
+compatibility: Any Agent Skills host. Needs the go toolchain.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "go"
+  kete-loom/owner: "Kete-org"
+---
+
+# Go testing
+
+Use the standard `testing` package and the project's existing test style. Add an assertion library only if the project already uses one.
+
+## 0. Before you write
+
+1. Find the test command (Makefile, CI workflow, README). Default: `go test ./...`.
+2. Run the package's tests once and record the result. If they already fail, **stop and tell the user** which ones before changing anything.
+3. Read the `go` directive in `go.mod`; do not use testing APIs newer than it.
+4. Look at a neighbouring `_test.go` file for naming, helpers, fixtures and whether tests are in `package foo` (white-box) or `package foo_test` (black-box). Prefer `foo_test` for testing the public API.
+
+## 1. Table-driven tests with subtests
+
+```go
+func TestParseDuration(t *testing.T) {
+	tests := []struct {
+		name    string
+		in      string
+		want    time.Duration
+		wantErr bool
+	}{
+		{name: "minutes", in: "5m", want: 5 * time.Minute},
+		{name: "empty", in: "", wantErr: true},
+		{name: "negative", in: "-1s", wantErr: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := ParseDuration(tt.in)
+			if (err != nil) != tt.wantErr {
+				t.Fatalf("ParseDuration(%q) error = %v, wantErr %v", tt.in, err, tt.wantErr)
+			}
+			if got != tt.want {
+				t.Errorf("ParseDuration(%q) = %v, want %v", tt.in, got, tt.want)
+			}
+		})
+	}
+}
+```
+
+Rules:
+- Every case has a `name`; run one with `go test -run 'TestParseDuration/negative' ./pkg`.
+- Failure messages say `Func(input) = got, want want`. Use `t.Errorf` to keep going, `t.Fatalf` only when later checks would be meaningless.
+- Compare structs and slices with `github.com/google/go-cmp/cmp` (`cmp.Diff(want, got)`) if available, otherwise `reflect.DeepEqual`. Check errors with `errors.Is`, not string equality.
+- `t.Parallel()` only when cases share no mutable state. On modules with a `go` directive before 1.22, copy the loop variable (`tt := tt`) before a parallel subtest.
+
+## 2. Helpers and cleanup
+
+- Call `t.Helper()` first in every helper that calls `t.Fatal`/`t.Error`, so failures point at the caller.
+- Helpers take `t *testing.T` (or `testing.TB` to share with benchmarks) and fail directly instead of returning errors.
+- Use `t.Context()` (Go 1.24+, cancelled just before cleanup runs) instead of `context.Background()` in tests where available.
+- Use `t.Cleanup(fn)` for teardown, `t.TempDir()` for files, `t.Setenv` for environment variables (it cannot be combined with `t.Parallel`).
+- Put fixture files in `testdata/`; the go tool ignores that directory when building.
+
+## 3. Fakes over mocks
+
+- Depend on a small interface at the consumer, then write a fake by hand in the test file: a struct with fields recording calls and returning canned results.
+- Prefer real implementations when they are cheap: `bytes.Buffer` for `io.Writer`, `fstest.MapFS` for `fs.FS`, `httptest` for HTTP, an in-memory store.
+- Do not add a mock generator to a project that does not already use one. Never mock the unit under test.
+- Inject time and randomness (`now func() time.Time`, a seeded `*rand.Rand`) instead of sleeping or relying on wall time.
+
+## 4. HTTP
+
+- Handlers: `rec := httptest.NewRecorder(); req := httptest.NewRequest(http.MethodGet, "/items/1", nil); h.ServeHTTP(rec, req)`, then check `rec.Code`, headers and `rec.Body`.
+- Clients: `srv := httptest.NewServer(http.HandlerFunc(...)); defer srv.Close()` and point the client at `srv.URL`. Use `httptest.NewTLSServer` with `srv.Client()` for TLS.
+- Assert the request the fake server received (method, path, body) as well as the client's result.
+- No real network calls in unit tests.
+
+## 5. Concurrency and the race detector
+
+- Run `go test -race ./...` for any package with goroutines or shared state. A race report is a bug to fix, not a flake.
+- Never use `time.Sleep` to wait for a goroutine. Wait on a channel, a `sync.WaitGroup`, or poll a condition with a deadline.
+- For code built on timers and goroutines, the `testing/synctest` package (`synctest.Test`, Go 1.25+) runs the test in a bubble with a fake clock; use it if the module's Go version allows.
+- Find flakes with `go test -race -count=50 -run TestName ./pkg`. Use `-shuffle=on` to expose order dependence.
+
+## 6. Fuzzing
+
+```go
+func FuzzParseDuration(f *testing.F) {
+	for _, s := range []string{"5m", "", "1h30m", "-1s"} {
+		f.Add(s)
+	}
+	f.Fuzz(func(t *testing.T, s string) {
+		d, err := ParseDuration(s)
+		if err != nil {
+			return
+		}
+		if again, err := ParseDuration(d.String()); err != nil || again != d {
+			t.Fatalf("round trip %q -> %v -> %v, %v", s, d, again, err)
+		}
+	})
+}
+```
+
+- Run with `go test -fuzz=FuzzParseDuration -fuzztime=30s ./pkg`. Only one fuzz target per package per run.
+- Assert properties (round trip, no panic, invariants), not exact outputs.
+- Failing inputs are written to `testdata/fuzz/FuzzName/`. Commit them: they become regression cases run by a plain `go test`.
+
+## 7. Benchmarks
+
+- Name `BenchmarkXxx(b *testing.B)`. On Go 1.24+ write the loop as `for b.Loop() { ... }`; setup before the loop is excluded automatically. On older versions use `for i := 0; i < b.N; i++` with `b.ResetTimer()` after setup.
+- Run with `go test -run '^$' -bench BenchmarkName -benchmem -count=10 ./pkg`.
+- Compare before and after with `golang.org/x/perf/cmd/benchstat old.txt new.txt`. Never claim a speed-up from a single run.
+
+## 8. Golden files
+
+```go
+var update = flag.Bool("update", false, "rewrite golden files")
+
+func TestRender(t *testing.T) {
+	got := Render(input)
+	golden := filepath.Join("testdata", t.Name()+".golden")
+	if *update {
+		if err := os.WriteFile(golden, got, 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	want, err := os.ReadFile(golden)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if diff := cmp.Diff(string(want), string(got)); diff != "" {
+		t.Errorf("Render mismatch (-want +got):\n%s", diff)
+	}
+}
+```
+
+Regenerate with `go test ./pkg -run TestRender -update`, then **read the diff** before committing. Subtest names contain `/`; sanitise or create directories when using `t.Name()` in a path.
+
+## 9. Coverage
+
+`go test -coverprofile=cover.out ./... && go tool cover -func=cover.out`. Cover the error paths and boundaries the user cares about; do not chase a percentage.
+
+## Never
+
+- Delete, skip (`t.Skip`) or weaken an existing test to get green without the user's agreement.
+- Sleep to synchronise, hit the real network, or depend on test execution order.
+- Leave goroutines running after a test returns.
+
+## Report back
+
+End with: tests added or changed (names), the exact commands run (including `-race`), pass/fail counts, and anything left untested.

package/skills/go-testing/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Write table-driven tests with subtests for my Go ParseAmount function",
+    "This Go test is flaky under -race and uses time.Sleep, make it deterministic",
+    "Test my Go HTTP handler for POST /orders using httptest without a real server",
+    "Add a fuzz target for the Go URL normaliser and commit any crashing inputs",
+    "Benchmark these two Go JSON encoders properly and compare them with benchstat",
+    "Replace the gomock mocks in this _test.go file with a simple hand-written fake"
+  ],
+  "should_not_trigger": [
+    "How should I structure packages and interfaces in my new Go service?",
+    "Review this Go diff for data races and context misuse before I merge",
+    "go vet reports 'copylocks: call of foo copies lock value', fix the build",
+    "Write pytest fixtures and parametrized tests for my Flask app",
+    "Add Playwright end-to-end tests for the signup page"
+  ]
+}

package/skills/google-workspace-integration/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: google-workspace-integration
+description: Calls the Google Drive v3, Docs, Sheets and Slides REST APIs from application code, covering the choice between user OAuth, a service account and domain-wide delegation, the narrowest scopes (drive.file before restricted drive), files.list queries with shared-drive flags, documents and presentations batchUpdate requests applied in descending index order, Sheets A1 ranges with valueInputOption, and per-minute quotas handled with truncated exponential backoff on 429 and 403 rate errors. Use when code must create, read, fill or export Google Docs, Sheets, Slides or Drive files, a service account gets 403 or storageQuotaExceeded, or a Workspace sync hits rate limits.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to googleapis.com and a Google Cloud project with the APIs enabled. Examples use the official googleapis client libraries; the rules apply to raw REST too.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Google Workspace integration
+
+Build Drive, Docs, Sheets and Slides automation that asks for the least access, acts as the right identity, survives quota limits and does not corrupt documents with misplaced indexes. For Cloud IAM, Cloud Run and other Google Cloud infrastructure use `gcp-patterns`; this skill is about Workspace content APIs.
+
+## Ground rules
+
+1. **Pick the identity first** (table below). It decides scopes, file ownership and whether an admin must be involved.
+2. **Narrowest scope that works.** `drive.file` (only files the app created or the user opened with it) is non-sensitive; `drive`, `drive.readonly` and `drive.metadata*` are restricted and need Google's restricted-scope verification for a public app. Prefer `spreadsheets`, `documents` or `presentations` plus `drive.file` over full `drive`.
+3. **Credentials stay out of code.** OAuth client secrets, refresh tokens and service account key JSON come from a secret store or environment. Prefer keyless service account auth (attached service account, Workload Identity Federation) over downloaded key files.
+4. **Batch, and treat a batch as one unit.** Sheets, Docs and Slides `batchUpdate` apply all requests atomically: one invalid request means none apply. Each batch counts as one request against quota.
+5. **Back off on rate errors.** Retry 429, and 403 with reason `userRateLimitExceeded` or `rateLimitExceeded`, plus 5xx, with truncated exponential backoff: wait `min(2^n seconds + random up to 1000 ms, 32 to 64 s)`, then give up after a bounded number of tries. Never retry 400, 401 or a 403 for permissions.
+6. **Ask only for the fields you use.** Pass `fields` on Drive and Docs reads (`files(id,name,mimeType,modifiedTime),nextPageToken`); it cuts payload and latency.
+
+## Choose the identity
+
+| Situation | Use |
+|---|---|
+| Users act on their own files (an add-on, a "connect Google Drive" button) | OAuth 2.0 user consent, offline access for a refresh token, incremental scopes |
+| A backend job owns its own documents or works in a team folder | Service account; give it access by sharing a **shared drive** or folder with its email |
+| A Workspace org's backend must act as many users without each consenting | Service account with **domain-wide delegation**: a super admin authorises the client ID and an exact scope list in the Admin console (API controls); the code impersonates a user with `subject` |
+
+Service accounts have no Drive storage of their own: creating files in a My Drive folder shared with them fails with `storageQuotaExceeded`. Put the work in a shared drive, or impersonate a real user with delegation. Cloud IAM roles do not grant access to Workspace files; sharing does.
+
+## Implementation steps
+
+1. **Project setup**: enable each API (Drive, Docs, Sheets, Slides) in the Google Cloud project, configure the OAuth consent screen with only the scopes you request, and create the OAuth client or service account.
+2. **Auth client**: build it once and reuse it; the libraries refresh access tokens. For delegation, set the subject user per request and keep the scope list identical to the one the admin approved, or token requests fail with `unauthorized_client`.
+3. **Drive**: find files with `files.list` and a `q` query; page with `pageToken` until `nextPageToken` is absent. For shared drives pass `supportsAllDrives=true` and `includeItemsFromAllDrives=true` (plus `corpora`/`driveId`), or results silently miss them. Create Google-native files by setting `mimeType` (for example `application/vnd.google-apps.document`). Export with `files.export` (10 MB cap on exported content). Query syntax and MIME types in `references/api.md`.
+4. **Sheets**: read and write values with `spreadsheets.values.get/update/append/batchGet/batchUpdate`. Write with `valueInputOption` `RAW` (stored literally) or `USER_ENTERED` (parsed like typing: formulas, dates). Read with `valueRenderOption` `UNFORMATTED_VALUE` when you need numbers, not display strings. Formatting, new tabs and protected ranges go through `spreadsheets.batchUpdate`, which addresses sheets by numeric `sheetId`, not title. A1 rules in `references/api.md`.
+5. **Docs**: `documents.get` returns a structure of elements with `startIndex`/`endIndex`; body text starts at index 1. In one `documents.batchUpdate`, order inserts and deletes from the highest index to the lowest so earlier edits don't shift later ones. For templates prefer `replaceAllText` on placeholders like `{{customer_name}}`. Pass `writeControl.requiredRevisionId` from your read to refuse a write if someone edited the doc in between.
+6. **Slides**: copy a template deck with Drive `files.copy`, then `presentations.batchUpdate` with `replaceAllText` and `replaceAllShapesWithImage` (image must be a public PNG, JPEG or GIF URL). Custom `objectId`s are 5 to 50 characters and unique in the deck.
+7. **Retries and idempotency**: wrap every call in the backoff helper. A retried create can make a second file, so before creating, search for an existing file by a stable name or an `appProperties` key you set, or generate IDs first with `files.generateIds` and create with that ID.
+8. **Watch for changes** with `changes.watch` or `files.watch` push channels to an HTTPS endpoint, or poll `changes.list` with a saved `startPageToken`. Channels expire; renew them before expiry.
+
+## Reviewing an existing integration
+
+- Full `drive` scope where `drive.file` would do; scopes requested that no code uses.
+- Service account key JSON committed or baked into an image.
+- Service account writing into a personal My Drive (fails on storage quota), or files left owned by an employee who may leave.
+- `files.list` without paging, without `fields`, or without shared-drive flags.
+- Docs edits applied in ascending index order, or text located by hard-coded indexes from an old copy of the template.
+- Sheets writes with `USER_ENTERED` on user-supplied text, so a value beginning with `=` becomes a live formula (formula injection); use `RAW` or prefix with `'`.
+- One API call per cell or row in a loop instead of a batch; no backoff, or retrying non-retryable errors.
+
+## Stop and ask the user
+
+- Before requesting a restricted scope (`drive`, `drive.readonly`, Gmail) for an app other people will install; it triggers Google's verification and possibly a security assessment.
+- Before setting up domain-wide delegation: it lets the service account act as any user for the approved scopes, and a super admin must approve it.
+- Before bulk-changing sharing permissions, deleting files or emptying trash.
+
+## Before you finish
+
+Quotas, scope classifications and limits change (Drive moved to per-unit quotas for projects created from May 2026), so check the official limits page for each API at developers.google.com/workspace. Test with a throwaway spreadsheet, document and shared drive; confirm a forced 429 is retried and a 403 permission error is not; confirm a retried create does not leave a duplicate file.

package/skills/google-workspace-integration/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Our Node backend should fill a Google Docs contract template with customer details and export it as a PDF",
+    "Append each new order as a row in a Google Sheet from our Python service using a service account",
+    "Service account upload to Drive fails with storageQuotaExceeded even though the folder is shared with it",
+    "Which OAuth scopes do we need to read files a user picks from their Google Drive without asking for full drive access?",
+    "Generate a weekly Google Slides report deck from a template and swap the chart placeholders for images",
+    "Our Sheets sync keeps getting 429 Too many requests, how should we batch and back off?"
+  ],
+  "should_not_trigger": [
+    "Grant a Cloud Run service account the right IAM role to read from Cloud Storage",
+    "Build a pivot table and VLOOKUP formulas in this Excel workbook",
+    "Write the Apps Script for a custom menu inside our spreadsheet",
+    "Our password reset emails sent through Amazon SES land in spam",
+    "Triage my Gmail inbox and draft replies for the important threads"
+  ]
+}

package/skills/google-workspace-integration/references/api.md

@@ -0,0 +1,121 @@
+# Google Workspace API reference notes
+
+Read this when writing Drive queries, Sheets ranges or batchUpdate bodies. Field names come from the v3 Drive, v4 Sheets, v1 Docs and v1 Slides REST references; confirm against developers.google.com/workspace if a call is rejected.
+
+## Scopes (prefix `https://www.googleapis.com/auth/`)
+
+| Scope | Classification | Grants |
+|---|---|---|
+| `drive.file` | non-sensitive | files the app created or the user opened with it (Picker) |
+| `drive.appdata` | non-sensitive | the app's hidden config folder |
+| `drive.readonly` | restricted | read every Drive file |
+| `drive` | restricted | read and write every Drive file |
+| `drive.metadata.readonly` | restricted | metadata of every file |
+| `spreadsheets.readonly` / `spreadsheets` | sensitive | all of the user's Sheets |
+| `documents.readonly` / `documents` | sensitive | all of the user's Docs |
+| `presentations.readonly` / `presentations` | sensitive | all of the user's Slides |
+
+## Drive `files.list` queries (`q`)
+
+```
+'FOLDER_ID' in parents and trashed = false
+mimeType = 'application/vnd.google-apps.spreadsheet'
+name contains 'Invoice' and modifiedTime > '2026-01-01T00:00:00'
+appProperties has { key='orderId' and value='A123' }
+```
+
+Escape a `'` inside a value as `\'`. Combine with `and`, `or`, `not`.
+
+Common params: `fields=nextPageToken,files(id,name,mimeType,parents,modifiedTime)`, `pageSize` (up to 1000), `pageToken`, `orderBy=modifiedTime desc`, `supportsAllDrives=true`, `includeItemsFromAllDrives=true`, `corpora=drive&driveId=...` for one shared drive.
+
+Native MIME types: `application/vnd.google-apps.document`, `.spreadsheet`, `.presentation`, `.folder`. Export targets include `application/pdf`, `text/csv` (first sheet only), `application/vnd.openxmlformats-officedocument.wordprocessingml.document`.
+
+Upload: `uploadType=media` for small content-only uploads, `multipart` for content plus metadata, `resumable` for large files or unreliable networks.
+
+## Drive quotas (projects created on or after 1 May 2026)
+
+Per-unit: 1,000,000 units per minute per project, 325,000 per minute per user per project. Costs: read 5, list 100, download 200, edit 50, other (e.g. `files.generateIds`) 5. Usage above 400,000,000 units per project per day may be billed, so prefer `changes.list` over repeated full `files.list` scans. 750 GB per user per day of uploads and copies across My Drive and shared drives. Projects that used the API between November 2025 and April 2026 keep their previous quotas. Errors: `403 userRateLimitExceeded`, `429`.
+
+## Sheets
+
+Quota: 300 read and 300 write requests per minute per project, 60 per minute per user per project; a batch counts as one request. Recommended payload under 2 MB; a request times out after 180 s.
+
+A1 notation:
+
+| Range | Meaning |
+|---|---|
+| `Sheet1!A1:C10` | block on Sheet1 |
+| `'Q3 Sales'!A:A` | whole column; quote titles with spaces or symbols, double any `'` inside |
+| `Sheet1!2:2` | whole row 2 |
+| `Sheet1!A5:C` | columns A-C from row 5 down |
+| `Sheet1` | whole sheet |
+| `A1:B2` | first visible sheet (avoid; be explicit) |
+
+Values calls:
+
+```http
+PUT /v4/spreadsheets/{id}/values/'Orders'!A2:C2?valueInputOption=RAW
+{ "values": [["A123", 4999, "paid"]] }
+
+POST /v4/spreadsheets/{id}/values/Orders!A:C:append?valueInputOption=RAW&insertDataOption=INSERT_ROWS
+{ "values": [["A124", 1500, "pending"]] }
+
+POST /v4/spreadsheets/{id}/values:batchUpdate
+{ "valueInputOption": "USER_ENTERED", "data": [ { "range": "Summary!B1", "values": [["=SUM(Orders!B:B)"]] } ] }
+```
+
+`valueRenderOption`: `FORMATTED_VALUE` (default, display strings), `UNFORMATTED_VALUE`, `FORMULA`. `dateTimeRenderOption`: `SERIAL_NUMBER` (default) or `FORMATTED_STRING`, only when not `FORMATTED_VALUE`.
+
+Structure changes use `spreadsheets.batchUpdate` with requests such as `addSheet`, `repeatCell` (with a `GridRange` of `sheetId`, zero-based, end-exclusive row and column indexes and a `fields` mask), `autoResizeDimensions`, `addProtectedRange`. Get `sheetId`s from `spreadsheets.get?fields=sheets.properties`.
+
+## Docs `documents.batchUpdate`
+
+```json
+{
+  "requests": [
+    { "replaceAllText": { "containsText": { "text": "{{customer_name}}", "matchCase": true }, "replaceText": "Ama Mensah" } },
+    { "insertText": { "location": { "index": 120 }, "text": "Second paragraph\n" } },
+    { "insertText": { "location": { "index": 1 }, "text": "Heading\n" } }
+  ],
+  "writeControl": { "requiredRevisionId": "<revisionId from documents.get>" }
+}
+```
+
+Order index-based edits highest index first. `targetRevisionId` instead of `requiredRevisionId` merges with collaborators' edits rather than failing.
+
+## Slides `presentations.batchUpdate`
+
+```json
+{
+  "requests": [
+    { "replaceAllText": { "containsText": { "text": "{{quarter}}", "matchCase": true }, "replaceText": "Q3 2026" } },
+    { "replaceAllShapesWithImage": { "containsText": { "text": "{{chart}}" }, "imageUrl": "https://example.com/chart.png", "imageReplaceMethod": "CENTER_INSIDE" } },
+    { "createSlide": { "objectId": "summary_slide_01", "slideLayoutReference": { "predefinedLayout": "TITLE_AND_BODY" } } }
+  ]
+}
+```
+
+Images: public PNG, JPEG or GIF, under 50 MB and 25 megapixels, URL at most 2 KB; fetched once at insert. `objectId`: 5-50 chars, first char `[a-zA-Z0-9_]`, then `[a-zA-Z0-9_-:]`.
+
+## Backoff helper (TypeScript)
+
+```ts
+const RETRYABLE = new Set(["rateLimitExceeded", "userRateLimitExceeded", "backendError"]);
+
+export async function withBackoff<T>(call: () => Promise<T>, maxTries = 6): Promise<T> {
+  for (let n = 0; ; n++) {
+    try {
+      return await call();
+    } catch (err: any) {
+      // googleapis/gaxios: HTTP status is on response.status; err.code may be a network code string like "ECONNRESET"
+      const status = err?.response?.status ?? (typeof err?.code === "number" ? err.code : undefined);
+      const reason = err?.response?.data?.error?.errors?.[0]?.reason ?? err?.errors?.[0]?.reason;
+      const network = status === undefined && ["ECONNRESET", "ETIMEDOUT", "EAI_AGAIN"].includes(err?.code);
+      const retryable = network || status === 429 || status >= 500 || (status === 403 && RETRYABLE.has(reason));
+      if (!retryable || n + 1 >= maxTries) throw err;
+      const wait = Math.min(2 ** n * 1000 + Math.random() * 1000, 64_000);
+      await new Promise((r) => setTimeout(r, wait));
+    }
+  }
+}
+```

package/skills/harmonyos-arkts/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: harmonyos-arkts
+description: Builds and fixes HarmonyOS NEXT apps written in ArkTS with ArkUI declarative components, choosing between the V1 state decorators (@State, @Prop, @Link, @Observed/@ObjectLink) and the V2 set (@ComponentV2, @Local, @Param, @Event, @ObservedV2/@Trace, @Monitor, @Computed) without mixing them illegally, wiring the UIAbility lifecycle and page routing, and running hvigorw and ohpm builds and clearing typical ArkTS compiler, signing and dependency errors. Use when writing or restructuring ArkUI pages and components, migrating state from V1 to V2 decorators, debugging a UI that does not refresh, or getting a HarmonyOS project in DevEco Studio or CI to build and install a HAP.
+license: MIT
+compatibility: Any Agent Skills host. Builds need the HarmonyOS SDK with hvigorw and ohpm (from DevEco Studio or the command-line tools); installing needs hdc and a device or emulator. Decorator availability depends on the API level in build-profile.json5.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "hvigorw, ohpm"
+  kete-loom/owner: "Kete-org"
+---
+
+# HarmonyOS ArkTS and ArkUI
+
+Write ArkTS that compiles under the strict ArkTS rules, keeps UI state observable, and builds the same way in DevEco Studio and CI.
+
+## 0. Before you start
+
+1. Read the project layout: `AppScope/app.json5` (bundle name, version), `build-profile.json5` (products, `compatibleSdkVersion`/`targetSdkVersion`, signing configs, modules), `oh-package.json5` (dependencies), each module's `src/main/module.json5` (abilities, permissions) and `src/main/resources/base/profile/main_pages.json` (routable pages).
+2. Note the API level. State management V2 needs API 12 or later; check the official docs for anything newer before using it.
+3. Find which state model the code uses: `@Component` structs are V1, `@ComponentV2` structs are V2. Follow the one already in use unless the user asks to migrate.
+4. Install dependencies and build once (section 4) before editing, and record the errors that already exist.
+
+## 1. ArkTS rules the compiler enforces
+
+ArkTS is stricter than TypeScript. Write it this way from the start:
+
+- No `any` or `unknown`; give everything an explicit type (`arkts-no-any-unknown`). Type `JSON.parse` results, for example as a declared class or `Record<string, Object>`.
+- Object literals must match a declared class or interface (`arkts-no-untyped-obj-literals`). Declare an `interface` or `class` and annotate.
+- No dynamic property access on objects by string index (`arkts-no-props-by-index`); use a `Map` or declared fields.
+- No structural typing tricks, no runtime-added fields, no `delete`, limited destructuring and spread; prefer classes and explicit types.
+- Import system APIs from kits: `@kit.AbilityKit`, `@kit.ArkUI`, `@kit.NetworkKit`, `@kit.PerformanceAnalysisKit` (for `hilog`).
+
+When the compiler names a rule tag, look it up in the official ArkTS migration guide ("Adaptation Cases") and apply its fix pattern; do not silence the check.
+
+## 2. Components and state
+
+A component is a `struct` with a decorator and a `build()` method that describes UI. Keep `build()` free of side effects; do work in lifecycle callbacks (`aboutToAppear`, `aboutToDisappear`) or event handlers.
+
+| Need | V1 (`@Component`) | V2 (`@ComponentV2`) |
+|---|---|---|
+| Local state | `@State` | `@Local` |
+| Read-only input from parent | `@Prop` (copied) | `@Param` (add `@Require` if mandatory) |
+| Input initialised once, then owned locally | `@State` initialised from parent | `@Param @Once` |
+| Child changes parent state | `@Link` | `@Param` plus an `@Event` callback the parent handles |
+| Pass down many levels | `@Provide` / `@Consume` | `@Provider()` / `@Consumer()` |
+| Observe nested object fields | `@Observed` class + `@ObjectLink` | `@ObservedV2` class with `@Trace` fields |
+| React to a change | `@Watch('method')` | `@Monitor('path')` |
+| Derived value | getter (recomputed each build) | `@Computed get` |
+| App-wide state | `AppStorage` / `@StorageLink` / `LocalStorage` | `AppStorageV2`, `PersistenceV2` |
+
+Rules:
+
+1. Never put V2 decorators inside a `@Component` struct or V1 decorators inside a `@ComponentV2` struct; it does not compile. A struct cannot be both.
+2. When mixing, a V1 component can contain a V2 child when no state is passed between them; passing state across the boundary has restrictions, so read the official "mixed scenarios" page before doing it, or migrate the whole subtree.
+3. `@Local` and `@State` observe assignment of the value and, for arrays, the mutating array methods (`push`, `splice`, index assignment). They do not see a field change inside an element or nested object: for that use `@ObservedV2` + `@Trace` (V2) or `@Observed` + `@ObjectLink` (V1).
+4. Data flows down; events flow up. A child never mutates a `@Param`; it calls the parent's `@Event`.
+5. Use `ForEach(items, (item: Item) => { ... }, (item: Item) => item.id.toString())` with a stable key generator that returns a string, and `LazyForEach` with an `IDataSource` for long lists.
+
+UI not refreshing? Check, in order: the field is decorated; the changed thing is the observed level (object vs field); the object is a decorated class instance and not a plain literal; the `ForEach` key changes when content changes.
+
+## 3. UIAbility lifecycle and pages
+
+1. The entry ability (`EntryAbility.ets`) extends `UIAbility`. Callbacks run in this order: `onCreate(want, launchParam)`, `onWindowStageCreate(windowStage)`, `onForeground()`, then `onBackground()`, `onWindowStageDestroy()`, `onDestroy()`.
+2. Load the first page in `onWindowStageCreate` with `windowStage.loadContent('pages/Index', (err) => { ... })` and log failures with `hilog`.
+3. Release resources in `onBackground` (pause timers, sensors) and in `onWindowStageDestroy` (UI listeners).
+4. Register every `@Entry` page in `main_pages.json`. For navigation, follow what the project uses; current docs recommend the `Navigation` component with `NavPathStack` over the older `router` module for new code. Check the docs for your API level.
+5. Declare permissions in `module.json5` and request user-granted ones at runtime with `abilityAccessCtrl`; never assume they are granted.
+
+## 4. Build and run
+
+From the project root:
+
+```sh
+ohpm install                                    # dependencies from oh-package.json5
+hvigorw clean --no-daemon
+hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon
+hdc install <module>/build/default/outputs/default/<module>-default-signed.hap
+```
+
+- The HAP lands under `<module>/build/<product>/outputs/<target>/`. Use `buildMode=release` for release builds.
+- Use `--no-daemon` in CI.
+- Installing on a device needs a signed HAP: configure `signingConfigs` in `build-profile.json5` (DevEco Studio can generate debug signing). Never commit keystores or passwords; read them from CI secrets.
+- If `hvigor/hvigor-config.json5` pulls npm packages, CI needs an npm registry configured.
+
+For specific build errors and their fixes, read `references/build-errors.md`.
+
+## 5. Verify
+
+1. The build finishes with no ArkTS errors and no new warnings.
+2. Install and launch on a device or emulator; open each changed page; exercise each state change and confirm the UI updates.
+3. Send to background and back; rotate if supported; confirm nothing leaks or crashes (`hdc hilog` for logs).
+4. Run the module's tests if the project has them (`ohosTest` source set).
+
+## Stop and ask the user
+
+- Migrating a whole app from V1 to V2 decorators, or from `router` to `Navigation`: confirm scope first.
+- Raising `compatibleSdkVersion`, changing the bundle name, or touching signing configs.
+- A third-party ohpm package has no HarmonyOS NEXT version.
+
+## Never
+
+- Never use `any`, `// @ts-ignore` or casts to get past ArkTS checks.
+- Never mix V1 and V2 decorators in one struct.
+- Never do network or file I/O inside `build()`.
+- Never commit signing material.
+
+## Report back
+
+```
+API level / state model: <API n, V1 or V2>
+Changed: <files and components>, decorators used: <list>
+Build: <commands run> -> <result>; installed on: <device/emulator>
+Checked in docs: <APIs>; not verified: <list>
+Follow-ups: <migration or signing items>
+```