Improve repository presentation

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,61 @@
+name: Bug report
+description: Report a Things Cloud SDK, CLI, MCP, or sync bug.
+title: "bug: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Do not paste Things credentials, tokens, HAR captures, or private task data.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What broke?
+    validations:
+      required: true
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Surface
+      options:
+        - SDK
+        - things-cloud-cli
+        - things-mcp
+        - sync engine
+        - local SQLite reader
+        - documentation
+        - other
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction
+      description: Include sanitized commands, inputs, or dry-run JSON when possible.
+      placeholder: |
+        1. Run ...
+        2. Expected ...
+        3. Actual ...
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Go version, Things Cloud SDK version/tag, Things app version if relevant.
+      placeholder: |
+        OS:
+        Go:
+        SDK tag:
+        Things app:
+    validations:
+      required: false
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs or output
+      description: Paste sanitized output only.
+      render: shell
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Things app support
+    url: https://culturedcode.com/things/support/
+    about: Contact Cultured Code for official Things app support.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,32 @@
+name: Feature request
+description: Suggest a new SDK, CLI, MCP, sync, or agent workflow capability.
+title: "feature: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What workflow are you trying to support?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the API, CLI command, MCP tool, or behavior you want.
+    validations:
+      required: true
+  - type: textarea
+    id: agent_contract
+    attributes:
+      label: Agent or JSON contract impact
+      description: If this affects agents, describe the expected stable input/output shape.
+    validations:
+      required: false
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false

.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## Summary
+
+- 
+
+## Verification
+
+- [ ] `go test ./...`
+
+## Notes
+
+- CLI/MCP JSON contract changed: no
+- Raw Things Cloud write payload changed: no
+- Docs updated: no

.github/workflows/go.yml

@@ -1,27 +1,29 @@
-
-name: Go
+name: CI
 
 on:
   push:
   pull_request:
 
-jobs:
+permissions:
+  contents: read
 
+jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
-    - name: Set up Go
-      uses: actions/setup-go@v4
-      with:
-        go-version: '1.23'
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
 
-    - name: Build
-      run: go build -v ./...
+      - name: Build
+        run: go build -v ./...
 
-    - name: Test
-      run: go test -v ./...
+      - name: Test
+        run: go test -v ./...
 
-    - name: Test Coverage
-      run: go test -cover ./...
+      - name: Test Coverage
+        run: go test -cover ./...

.gitignore

@@ -22,6 +22,7 @@
 *.env
 /tmp/
 .env
+.serena/
 
 # HAR files (may contain credentials)
 *.har

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+Thanks for improving this maintained Things Cloud SDK fork.
+
+This project is focused on safe automation around Things Cloud:
+
+- stable CLI and MCP JSON contracts
+- dry-run behavior for agent-generated writes
+- typed sync changes and persistent sync state
+- read-only local Things SQLite inspection
+- careful Things Cloud wire-format compatibility
+
+## Before Opening a PR
+
+Run:
+
+```bash
+go test ./...
+```
+
+For CLI write changes, also verify at least one `--dry-run` command and include
+the sanitized output shape in the PR description.
+
+Before changing raw write payloads, read `docs/client-side-bugs.md`. Small
+wire-format changes can break Things.app sync behavior.
+
+## Pull Request Notes
+
+Good PR descriptions include:
+
+- the user-facing behavior changed
+- CLI or MCP command examples, when relevant
+- whether JSON output contracts changed
+- the tests or smoke checks that ran
+
+Avoid unrelated refactors in behavior PRs. This repo is small enough that scoped
+changes are easier to review and safer to ship.
+
+## Secrets
+
+Do not commit credentials, Things Cloud tokens, HAR captures, or local Things
+database files. If a repro needs sensitive data, reduce it to sanitized JSON or
+describe the relevant fields.

README.md

@@ -1,25 +1,46 @@
 # Things Cloud SDK
 
-[![Go](https://github.com/pdurlej/things-cloud-sdk/actions/workflows/go.yml/badge.svg)](https://github.com/pdurlej/things-cloud-sdk/actions/workflows/go.yml)
+[![CI](https://github.com/pdurlej/things-cloud-sdk/actions/workflows/go.yml/badge.svg)](https://github.com/pdurlej/things-cloud-sdk/actions/workflows/go.yml)
+[![Latest release](https://img.shields.io/github/v/release/pdurlej/things-cloud-sdk)](https://github.com/pdurlej/things-cloud-sdk/releases)
+[![Go Reference](https://pkg.go.dev/badge/github.com/pdurlej/things-cloud-sdk.svg)](https://pkg.go.dev/github.com/pdurlej/things-cloud-sdk)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Unofficial Go SDK, CLI, and MCP server for the Things Cloud sync API used by
-[Things](https://culturedcode.com/things/).
+Maintained Go SDK, CLI, and MCP server for automating
+[Things](https://culturedcode.com/things/) through the Things Cloud sync API.
 
-This maintained fork is optimized for automation and agent workflows, especially
-OpenClaw-style integrations that need predictable reads, safe writes, compact
-JSON, and a stable Things Cloud module path.
+Use it when you want Things automation that is cross-platform, scriptable, and
+agent-friendly without writing directly to the local Things SQLite database.
 
 ```text
 Go module:      github.com/pdurlej/things-cloud-sdk
 Preferred CLI:  things-cloud-cli
 Compat CLI:     things-cli
 MCP server:     things-mcp
-Current use:    cloud API reads/writes, persistent sync, local read-only SQLite
+Latest release: v0.2.3
+Focus:          safe writes, stable JSON, MCP tools, persistent sync
 Maintainer:     https://github.com/pdurlej
 ```
 
-The API is reverse engineered. Treat write paths carefully, use dry runs for
-agent-generated changes, and pin release tags in production agent environments.
+## What You Can Do
+
+- Read Things tasks from Inbox, Today, Anytime, Someday, Upcoming, projects,
+  areas, tags, search results, and completed/logbook history.
+- Create, edit, complete, trash, move, and batch-update tasks from a CLI or MCP
+  host.
+- Preview write payloads with `--dry-run` before touching Things Cloud.
+- Run a persistent sync cache with typed change events for services,
+  dashboards, and feedback loops.
+- Inspect local macOS Things data through a read-only SQLite adapter.
+
+## Project Status
+
+This is a maintained, unofficial fork focused on reliable automation and agent
+integrations. It is not affiliated with Cultured Code, and the Things Cloud API
+is reverse engineered.
+
+Production agents should pin release tags, use `--dry-run` for generated
+writes, and avoid writing to the local Things SQLite database. The local reader
+is intentionally read-only.
 
 ## LLM Integration Summary
 
@@ -584,10 +605,3 @@ go build -o things-mcp ./cmd/things-mcp
 
 Before changing write payloads, read `docs/client-side-bugs.md` and add focused
 tests. Small-looking wire-format changes can break Things.app sync behavior.
-
-## Project Status
-
-This is not an official Cultured Code API. All requests and payloads are based on
-reverse engineering. Contributions should preserve the automation-friendly
-contract: stable JSON, safe dry-run behavior, typed sync changes, and explicit
-separation between Cloud writes and local read-only inspection.

SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+This is an unofficial, reverse-engineered Things Cloud SDK. It may handle Things
+Cloud credentials, local cache files, and task data.
+
+## Supported Versions
+
+Security fixes target the latest tagged release and `main`.
+
+## Reporting a Vulnerability
+
+Do not paste credentials, tokens, HAR captures, or private task data into a
+public issue.
+
+If GitHub private vulnerability reporting is available for this repository, use
+it. Otherwise, open a minimal public issue without secrets and ask for a private
+contact path.
+
+If a credential may have been exposed, rotate or revoke it before debugging.
+
+## Handling Sensitive Repros
+
+Preferred repro formats:
+
+- sanitized CLI commands
+- sanitized dry-run JSON
+- minimal redacted snippets from Things Cloud payloads
+- clear expected vs actual behavior
+
+Avoid attaching full local Things databases or network captures.