@yuiseki/gyazocli 0.5.1 → 0.6.0

package/README.md

@@ -129,7 +129,8 @@ results back from the detail endpoint to confirm the filter had applied:
 | `title:`, `url:`, `desc:` | the page it was captured from |
 | `ocr:` | the text in the image |
 | `type:png` | the file type |
-| `since:2026-08-30 until:2026-08-31` | the upload date |
+| `date:2026-08-30`, `date:2026-08`, `date:2026` | the upload date, by day, month or year |
+| `since:2026-08-30 until:2026-08-31` | the upload date, as a range |
 | `-address:広島` | negation |
 | `OR` | alternation; terms are ANDed otherwise |
 
@@ -195,6 +196,22 @@ already configured against that server can point at this one instead. Its
 `gyazo_upload` is deliberately absent: nothing here can write to your Gyazo
 account until there is a reason for it to.
 
+## Agent skill
+
+`skills/gyazo/` is a skill for coding agents that drive the CLI: what the
+commands are, what the search syntax actually accepts, and the judgement calls
+that keep a capture from becoming a claim it does not support. It ships in the
+npm package.
+
+Install it for Claude Code by copying it where the agent looks for skills:
+
+```bash
+mkdir -p ~/.claude/skills
+cp -r "$(npm root -g)/@yuiseki/gyazocli/skills/gyazo" ~/.claude/skills/
+```
+
+Per project instead of per user, copy it to `.claude/skills/` in the project.
+
 ## Development
 
 ### Build

package/dist/api.js

@@ -119,7 +119,11 @@ async function listCollectionImages(collectionId, page = 1, per = 100) {
  */
 async function fetchImageRendition(imageId, width, format = 'webp') {
     const extension = format === 'jpeg' ? 'jpg' : 'webp';
-    const url = `${imageOrigin()}/thumb/${width}_w/${imageId}.${extension}`;
+    // The `-jpg` before the extension is a source-type marker, and it has to be
+    // there: without it the route answers 404 for any capture whose derivative
+    // is not already stored, which is most of them. Its value is ignored, and
+    // the extension alone decides what comes back, so a constant will do.
+    const url = `${imageOrigin()}/thumb/${width}_w/${imageId}-jpg.${extension}`;
     const response = await axios_1.default.get(url, { responseType: 'arraybuffer' });
     const data = Buffer.from(response.data);
     const contentType = String(response.headers['content-type'] || '').split(';')[0].trim();

package/dist/index.js

@@ -26,7 +26,7 @@ program
     .name('gyazo')
     .description('Gyazo Memory CLI for AI Secretary')
     .option('--mcp-server', 'run as a Model Context Protocol server over stdio')
-    .version('0.5.1');
+    .version('0.6.0');
 (0, config_1.registerConfigCommand)(program);
 (0, list_1.registerListCommand)(program);
 (0, get_1.registerGetCommand)(program);

package/dist/mcp.js

@@ -46,9 +46,10 @@ const SEARCH_QUERY_DESCRIPTION = [
     'and case, and matches postal codes too, so address:広島 and address:Hiroshima and',
     'address:730-0041 all find the same photos.',
     'Also: app: the application it came from; title:, url: and desc: the page it was',
-    'captured from; ocr: the text in the image; type: the file type, as type:png; since:',
-    'and until: bound the upload date, as since:2026-08-30 until:2026-08-31. Quote a value',
-    'that contains spaces.',
+    'captured from; ocr: the text in the image; type: the file type, as type:png; date:',
+    'a day, a month or a year of upload, as date:2026-08-30, date:2026-08 or date:2026;',
+    'since: and until: bound the upload date, as since:2026-08-30 until:2026-08-31. Quote a',
+    'value that contains spaces.',
     'There is no coordinate or radius search: location:, geo:, near:, bbox:, city: and the',
     'like all return nothing. To search by place, use address: with a place name.',
     'An operator Gyazo does not know returns nothing rather than matching as text, so an',
@@ -193,16 +194,35 @@ const INCLUDE_LOCATION = zod_1.z
     .boolean()
     .default(true)
     .describe('Fill in the location, which the listing and search endpoints leave out. Costs one ' +
-    'extra lookup per capture the local cache does not already hold. Set false when the ' +
-    'coordinates do not matter');
+    'extra lookup per capture the local cache does not already hold, so a page of 40 ' +
+    'uncached captures adds a few seconds; the next look at the same captures is free. ' +
+    'Set false when the coordinates do not matter');
+/**
+ * Fill in the locations, and say so when the per-call limit stopped it part
+ * way: past that point a capture without a location is indistinguishable from
+ * one that has none, which is exactly the sort of silence worth breaking.
+ */
 async function withLocations(images, includeLocation) {
-    return includeLocation ? (0, memory_1.enrichImageLocations)(images) : images;
+    if (!includeLocation)
+        return { images };
+    const result = await (0, memory_1.enrichImageLocations)(images);
+    if (result.skipped === 0)
+        return { images: result.images };
+    return {
+        images: result.images,
+        note: `The location was filled in for ${result.considered} captures; ${result.skipped} were ` +
+            'left as the listing returned them, so their missing location means "not looked up" ' +
+            'rather than "no location". Ask for fewer at a time to cover them all.',
+    };
 }
-function asMetadataListResult(images) {
+function asMetadataListResult(images, note) {
     if (!images || images.length === 0) {
         return NO_IMAGES;
     }
-    return asJsonResult(images.map(toMetadata));
+    const json = asJsonResult(images.map(toMetadata));
+    if (!note)
+        return json;
+    return { content: [...json.content, { type: 'text', text: note }] };
 }
 /**
  * A date argument, refused by throwing. The CLI reports and exits here, which
@@ -249,7 +269,8 @@ function createMcpServer() {
         if (!images || images.length === 0) {
             return NO_IMAGES;
         }
-        return asMetadataListResult(await withLocations(images, includeLocation));
+        const withLocation = await withLocations(images, includeLocation);
+        return asMetadataListResult(withLocation.images, withLocation.note);
     }));
     server.registerTool('gyazo_image', {
         title: 'Describe one Gyazo capture',
@@ -365,7 +386,8 @@ function createMcpServer() {
             hour: hour || undefined,
             alias,
         });
-        return asMetadataListResult(await withLocations(images, args.include_location));
+        const withLocation = await withLocations(images, args.include_location);
+        return asMetadataListResult(withLocation.images, withLocation.note);
     }));
     server.registerTool('gyazo_summary', {
         title: 'Summarise a stretch of Gyazo captures',
@@ -535,7 +557,8 @@ function createMcpServer() {
                 'recent pages of captures. It may be older than that, or belong to another ' +
                 'account. Ask for a window in minutes instead, or raise max_pages.');
         }
-        return asMetadataListResult(await withLocations(result.images, args.include_location));
+        const withLocation = await withLocations(result.images, args.include_location);
+        return asMetadataListResult(withLocation.images, withLocation.note);
     }));
     server.registerTool('gyazo_collections', {
         title: 'Find a Gyazo collection by name',

package/dist/services/memory.js

@@ -416,26 +416,23 @@ async function listCapturesSince(options) {
     }
     return { images: collected.slice(0, limit), pagesWalked };
 }
-/**
- * Fill in what the lean endpoints leave out.
- *
- * The listing and the search endpoints return an image without its
- * coordinates or its address, whatever the capture actually carries; only the
- * detail endpoint has them. So a caller that needs a location has to ask again
- * per image, which is what this does: the cache first, the API for the rest,
- * a few at a time, writing what it fetches back to the cache so the next look
- * is free.
- */
 async function enrichImageLocations(images, options = {}) {
     const useCache = options.useCache !== false;
     const limit = options.limit ?? 40;
-    const concurrency = Math.max(1, options.concurrency ?? 5);
+    const concurrency = Math.max(1, options.concurrency ?? 10);
     const enriched = [...images];
     const pending = [];
-    for (let index = 0; index < enriched.length && pending.length < limit; index++) {
+    let considered = 0;
+    let skipped = 0;
+    for (let index = 0; index < enriched.length; index++) {
         const image = enriched[index];
         if (image?.metadata?.exif_normalized || image?.metadata?.exif_address)
             continue;
+        if (considered >= limit) {
+            skipped++;
+            continue;
+        }
+        considered++;
         if (useCache) {
             const cached = (0, storage_1.loadImageCache)(image?.image_id);
             if (cached) {
@@ -459,5 +456,5 @@ async function enrichImageLocations(images, options = {}) {
             }
         }));
     }
-    return enriched;
+    return { images: enriched, considered, skipped };
 }

package/docs/ADR/003-cli-structure.md

@@ -13,7 +13,7 @@ Adopt and document the existing top-level command structure.
 
 ### 1. Program Metadata
 - Binary name: `gyazo`
-- Version: `0.5.1`
+- Version: `0.6.0`
 - Description: `Gyazo Memory CLI for AI Secretary`
 
 ### 2. Commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuiseki/gyazocli",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Gyazo Memory CLI for AI Secretary",
   "repository": {
     "type": "git",
@@ -16,6 +16,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "docs"
   ],

package/skills/gyazo/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: gyazo
+description: Search, read and summarise a person's Gyazo captures from the command line with the `gyazo` CLI - screenshots and phone photos, their OCR text, the application or page they came from, and where they were taken. Use when asked what someone saw, captured, read, bought, visited or worked on, when a question needs evidence from their screen history, or when a Gyazo image ID, a gyazo.com URL or a collection needs to be read.
+---
+
+# Gyazo CLI
+
+`gyazo` reads a Gyazo account: screenshots, phone photos, their OCR text, the
+application and page a capture came from, and the coordinates and address of a
+photo. It caches everything it reads under `~/.cache/gyazocli`, so repeated
+questions about the same period are answered locally.
+
+Check `gyazo config get me` first when a token might be missing; it prints the
+account or exits non-zero. Set one with `gyazo config set token <token>`.
+
+Every command exits non-zero on failure, so `&&` chains and `set -e` behave.
+
+## Reading captures
+
+```bash
+gyazo ls --limit 10                  # most recent, newest first
+gyazo ls --date 2026-08-30           # a local day; also yyyy-mm and yyyy
+gyazo ls --today
+gyazo ls --hour 2026-08-30-14        # one hour, from the cache only
+gyazo ls --photos                    # shorthand for has:location
+gyazo get <image_id>                 # one capture in detail
+gyazo get <image_id> --ocr           # just the OCR text
+gyazo <image_id>                     # same as get
+gyazo <https://gyazo.com/...>        # same as get
+gyazo ./screenshot.png               # an existing file uploads instead
+```
+
+Add `-j`/`--json` to any of these when the output is going to be parsed rather
+than read. Add `--no-cache` when the answer must come from the API.
+
+## Searching
+
+`gyazo search <query>` takes Gyazo's own query language. The operators below
+were confirmed against the live API; see [references/search-syntax.md](references/search-syntax.md)
+for the measurements behind them and the ones that do not exist.
+
+```bash
+gyazo search "お好み焼"                        # OCR text, title and description
+gyazo search "has:exif"                        # photographs, not screenshots
+gyazo search "address:広島"                    # where a photo was taken
+gyazo search "date:2026-08-30"                 # a day, a month or a year
+gyazo search 'app:"Gyazo Android"'             # the application it came from
+gyazo search "ocr:Wi-Fi has:exif"              # terms are ANDed
+gyazo search "address:広島 OR address:京都"     # capital OR
+gyazo search "has:location -app:Chrome"        # leading - negates
+```
+
+Three things worth knowing before composing a query:
+
+- **An operator Gyazo does not know returns nothing**, rather than falling back
+  to a text search. A guessed operator looks exactly like "no such captures".
+- **`has:exif` is how to narrow to photographs.** The application does not tell
+  them apart: `app:"Gyazo Android"` includes screenshots and screen recordings
+  from the same phone.
+- **There is no coordinate or radius search.** Search by place with `address:`,
+  which matches the address in any language and matches postal codes too.
+
+## Summaries and rankings
+
+```bash
+gyazo summary                        # the week to yesterday, day by day
+gyazo summary --date 2026-08-30
+gyazo stats --days 30                # one markdown report
+gyazo apps --date 2026-08            # what applications, most used first
+gyazo domains --today
+gyazo tags --date 2026
+gyazo locations --date 2026-08-30
+```
+
+The ranking commands take `--date`, `--today`, `--limit`, `--max-pages`,
+`--json` and `--no-cache`. Only `stats` takes `--days`.
+
+## Collections
+
+```bash
+gyazo collection <collection_id>
+gyazo collection https://gyazo.com/collections/<id>
+gyazo collection <id> --sort captured   # added | created | captured
+gyazo collection <id> --anonymous       # read a public one without the token
+```
+
+A collection ID and an image ID are both 32 hex characters and cannot be told
+apart on their own, which is why `gyazo <bare id>` reads it as an image. Pass
+the `/collections/<id>` URL when the ID is a collection.
+
+A collection larger than 100 images is reported as truncated: the public
+endpoint returns the first 100 and cannot page.
+
+## Filling the cache
+
+```bash
+gyazo sync --days 7                  # yesterday back through 7 days
+gyazo sync --date 2026-08            # a whole month
+```
+
+`sync` covers yesterday backwards and never today, because today is still
+happening. For anything from today use `ls --today`, `search`, or a ranking
+command with `--today`.
+
+## Answering questions with captures
+
+- A day is a local day. `--date 2026-08-30` means that date in this machine's
+  timezone, which is also how the cache is laid out.
+- Prefer `search` with an operator over `ls` plus filtering. The API does the
+  work, and `ls --date` over a wide range walks many pages.
+- OCR text is noisy: it comes from screenshots at whatever resolution, and
+  `locale` is often `und`. Treat it as a hint, not a transcript.
+- `get --objects` prints detected objects, but the API no longer returns the
+  field it reads, so it exits non-zero with "Object annotations not found" on
+  every capture tested. Use the OCR text instead.
+- **Do not turn a capture into a claim it does not support.** A product page or
+  a cart is interest; an order confirmation or a payment receipt is a purchase.
+  Say which capture the conclusion rests on.
+- A phone photo carries coordinates and a reverse-geocoded address in
+  `metadata.exif_normalized` and `metadata.exif_address` of the `--json`
+  output; the top-level `exif_normalized` is always null. Screenshots carry
+  neither.
+
+## Serving the same data over MCP
+
+`gyazo --mcp-server` runs the same functionality as a Model Context Protocol
+server over stdio, for a client that speaks MCP rather than shell. Everything
+above is the shell path.

package/skills/gyazo/references/search-syntax.md

@@ -0,0 +1,79 @@
+# Gyazo search syntax, as measured
+
+Every operator here was run against the live API with a value that should
+match, and the results were read back from the image detail endpoint to confirm
+the filter had actually applied. Counting results is not enough: a lean search
+response does not carry the field being filtered on, so a count can look right
+while the filter does nothing.
+
+Measured on 2026-09-09 and 2026-09-12.
+
+## Contents
+
+- [Operators that work](#operators-that-work)
+- [Operators that do not exist](#operators-that-do-not-exist)
+- [Combining terms](#combining-terms)
+- [Photographs versus screenshots](#photographs-versus-screenshots)
+- [What a search result does not contain](#what-a-search-result-does-not-contain)
+
+## Operators that work
+
+| Operator | Matches | Notes |
+| --- | --- | --- |
+| bare words | OCR text, title, description | `お好み焼` |
+| `address:` | the reverse-geocoded address of a capture with GPS | any language, any case, postal codes too: `address:広島`, `address:Hiroshima`, `address:730-0041` all find the same photos |
+| `date:` | upload date | `date:2026-08-30`, `date:2026-08`, `date:2026` |
+| `since:` / `until:` | upload date range | `since:2026-08-30 until:2026-08-31` |
+| `app:` | the application the capture came from | quote a value with spaces: `app:"Gyazo Android"` |
+| `title:`, `url:`, `desc:` | the page it was captured from | |
+| `ocr:` | the text in the image | |
+| `type:` | the file type | `type:png` |
+| `has:location` | captures with coordinates | |
+| `has:exif` | captures with EXIF | not the same set as `has:location` |
+
+## Operators that do not exist
+
+`location:`, `geo:`, `near:`, `bbox:`, `latlng:`, `city:`, `pref:`,
+`locality:`, `admin1:`, `country:`, `postal:`, `zip:`, `lat:`, `lng:`,
+`place:`, `around:`, `within:`, `radius:`, `before:`, `after:`, `day:`,
+`has:ocr`, `has:address`.
+
+All of them return zero results, exactly as an invented operator does
+(`zzz:広島` returns nothing while `広島` returns many). **Zero results from an
+unfamiliar operator means the operator, not the account.** Retry with a known
+one before concluding the captures do not exist.
+
+There is no coordinate or radius search of any kind. To search by place, use
+`address:` with a place name.
+
+## Combining terms
+
+- Terms are ANDed: `address:広島 address:東京` returns nothing, because no
+  capture is in both places.
+- `OR` in capitals works: `address:広島 OR address:東京`.
+- `|` does not work.
+- A leading `-` negates: `has:location -address:広島`.
+
+## Photographs versus screenshots
+
+`has:exif` is the filter that means photographs. The application does not tell
+them apart: one page of `app:"Gyazo Android" -has:exif` came back as 68 gif and
+30 png against 2 jpg, which is screen recordings and screenshots from the same
+phone.
+
+`has:exif` and `has:location` overlap without either containing the other. A
+photo taken indoors has EXIF and no coordinates; 86 captures in the account
+tested carried coordinates without the EXIF flag. `has:exif OR has:location` is
+the widest reading of "a photo".
+
+## What a search result does not contain
+
+The search and listing endpoints return a lean image: `metadata` holds `app`,
+`desc`, `title`, `url` and `original_*`, and nothing else. No coordinates, no
+address, no matter what the capture carries. Checked against a full page of 100
+where not one item had either field.
+
+Coordinates and addresses only come back from the detail endpoint, which is
+what `gyazo get <image_id> --json` calls. To answer "where were these taken",
+search for the IDs and then read each one; `gyazo` caches each detail, so the
+second pass over the same captures is local.