@yuchaocheng/yusijia 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -2,8 +2,11 @@
 
 Standalone compiled ESM CLI and bundled `family-content` Skill for macOS arm64/x64,
 Node >=20.20.2. Uses Node built-ins, public `exifr` and `zod`. No database or website
-source dependency. Photo scans use bounded macOS `sips` width/height probes in
-addition to byte-format validation. Directory and explicit-file scans do not require `unzip`; zip
+source dependency. Photo scans use lightweight image signatures and bounded macOS
+`sips` width/height probes, not a strict hand-written format validator. Original
+bytes, including auxiliary data after JPEG image endings, remain unchanged;
+signatures/dimensions do not constitute a full malware scan or exhaustive decode.
+Directory and explicit-file scans do not require `unzip`; zip
 scans require `/usr/bin/unzip` and fail clearly when unavailable.
 
 ## Installation
@@ -19,16 +22,24 @@ yusijia --help
 yusijia skills install
 ```
 
-Read the installed `family-content` Skill in your Agent. Beta versions of
+The default installation is `~/.agents/skills/family-content`, for user-level host
+discovery rather than a one-off task directory. Open a new Agent conversation and
+check that `family-content` appears in its available Skills. Hosts that use another
+directory need their supported path via `--dir`; explicitly reading SKILL.md can
+bootstrap a session but does not prove automatic discovery. After discovery, normal
+requests need only the family task and supplied material, not installation steps.
+First setup can be delegated to an Agent: install this public package, run
+`yusijia skills install`, and check host discovery. Beta versions of
 `yusijia update` stay on the `beta` tag; stable versions use `latest`. Updates never
-fall back between channels. No stable `latest` tag is published with this beta.
+fall back between channels. No stable version has been published; unversioned
+installs may also resolve to a beta, so acceptance installs must select `@beta`.
 
 Build and test a local tarball (not a release):
 
 ```sh
 pnpm -C family-cli build
 npm pack ./family-cli --pack-destination ./family-cli
-npm install --global /absolute/path/yuchaocheng-yusijia-0.1.0-beta.1.tgz
+npm install --global /absolute/path/yuchaocheng-yusijia-0.1.0-beta.2.tgz
 yusijia --help
 yusijia skills install
 ```
@@ -71,6 +82,12 @@ errors and account/permission refusals leave the credential unchanged.
 
 ## Prepare And Confirm
 
+Generic photo organization is photo-first: select originals and choose an existing
+or new album. Growth timeline events require established milestone significance,
+not ordinary travel scenes. Diaries are proposed only when requested. Inspect
+images when the host supports it, distinguish metadata/documents from actual
+experiences, and ask about important missing facts instead of inventing them.
+
 ```sh
 yusijia photos scan --input /absolute/photos --out ./scan.json
 yusijia photos scan --files /absolute/a.jpg --files /absolute/b.png --out ./scan.json
@@ -185,6 +202,16 @@ separate from mocked tests and isolated package installation.
 
 ## Development Checks
 
+For repository engineering checks, build the CLI and use `pnpm agent:dev <command>`
+at the workspace root. This entry fixes `http://127.0.0.1:3600`, uses the isolated
+HOME and working directory `.local/yusijia-dev`, and rejects remote site overrides.
+Plans, progress and installed test Skills stay there; pass absolute material paths,
+and relative plan/output paths are relative to this isolated directory. It never
+falls back to production. This repository-only helper is not part of the public
+package or a requirement for family use. A source-free beta acceptance conversation
+instead uses the public installed CLI, its own separate HOME and an explicit local
+site on every site command; this operational convention is not network isolation.
+
 ```sh
 pnpm -C family-cli test
 pnpm -C family-cli typecheck

package/dist/scan.js

@@ -11,22 +11,12 @@ import { privateDirectory } from './storage.js';
 const run = promisify(execFile);
 const supported = { '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.webp': 'image/webp' };
 export function imageMime(b) {
-    if (b.length >= 24 && b.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) && b.subarray(-8, -4).toString() === 'IEND')
+    // Identify formats here; macOS probes dimensions during scan. Preserve auxiliary bytes.
+    if (b.length >= 24 && b.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
         return 'image/png';
-    if (b.length >= 20 && b[0] === 0xff && b[1] === 0xd8 && b[b.length - 2] === 0xff && b[b.length - 1] === 0xd9) {
-        let i = 2, hasFrame = false;
-        while (i + 4 < b.length && b[i] === 0xff) {
-            const marker = b[i + 1], length = b.readUInt16BE(i + 2);
-            if (length < 2 || i + 2 + length > b.length)
-                break;
-            if ([0xc0, 0xc1, 0xc2].includes(marker) && length >= 8 && b.readUInt16BE(i + 5) && b.readUInt16BE(i + 7))
-                hasFrame = true;
-            if (marker === 0xda)
-                return hasFrame ? 'image/jpeg' : undefined;
-            i += length + 2;
-        }
-    }
-    if (b.length >= 20 && b.subarray(0, 4).toString() === 'RIFF' && b.subarray(8, 12).toString() === 'WEBP' && b.readUInt32LE(4) + 8 === b.length && ['VP8 ', 'VP8L', 'VP8X'].includes(b.subarray(12, 16).toString()))
+    if (b.length >= 20 && b.subarray(0, 3).equals(Buffer.from([255, 216, 255])))
+        return 'image/jpeg';
+    if (b.length >= 20 && b.subarray(0, 4).toString() === 'RIFF' && b.subarray(8, 12).toString() === 'WEBP')
         return 'image/webp';
 }
 export async function readPhoto(file, expected, scope) {

package/dist/skills.d.ts

@@ -4,6 +4,7 @@ export declare function installSkill(directory?: string, stateDir?: string): Pro
     directory: string;
     cliVersion: string;
     skillVersion: string;
+    nextStep: string;
 }>;
 export declare function updateSkills(stateDir?: string): Promise<{
     ok: boolean;

package/dist/skills.js

@@ -53,7 +53,8 @@ export async function installSkill(directory = defaultSkillDirectory(), stateDir
     await writeSkillFile(join(target, 'SKILL.md'), skill);
     await writePrivateJson(join(target, '.yusijia-skill.json'), { version: VERSION, hash: sha256(skill) });
     await writePrivateJson(registry, [...new Set([...installed, target])]);
-    return { directory: target, cliVersion: VERSION, skillVersion: VERSION };
+    return { directory: target, cliVersion: VERSION, skillVersion: VERSION,
+        nextStep: 'Open a new conversation and check that your Agent lists family-content. If it does not, use the host-supported skill directory; reading SKILL.md explicitly is not automatic discovery.' };
 }
 async function writeSkillFile(file, text) {
     const { writePrivateText } = await import('./storage.js');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuchaocheng/yusijia",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "description": "Family content CLI and Agent Skill for photos, albums, timelines and diaries",
   "license": "UNLICENSED",
   "publishConfig": { "access": "public", "tag": "beta", "registry": "https://registry.npmjs.org/" },

package/skills/family-content/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: family-content
-description: Use yusijia to prepare explicitly supplied photos and query or propose confirmed family albums, growth timeline events and diary changes.
+description: Organize and import supplied family or holiday photos into the family website, choose albums, and query or prepare growth milestones and diaries when requested. Use the yusijia CLI; preview content before user-confirmed writes.
 metadata:
   cli-version: '{{CLI_VERSION}}'
 ---
@@ -12,18 +12,58 @@ read credentials.json, request passwords/tokens, or copy browser cookies. This S
 contains instructions, not family data. Check `yusijia --version` and `yusijia --help`.
 The installed Skill and CLI should have the same version.
 
+## First Use
+
+If `yusijia` is missing, install `@yuchaocheng/yusijia` globally from
+`https://registry.npmjs.org/`, then run `yusijia skills install` without `--dir`.
+Use `@beta` only when the user explicitly requests a beta trial; otherwise use
+`@latest`. Never use sudo or a corporate registry. If installation cannot run,
+report the actual blocker rather than cloning the website or guessing a binary.
+Install into the default user-level directory for future host discovery, not just
+a task-local directory. A new conversation may be needed to discover the Skill;
+check the host's available Skills before claiming automatic activation. Once
+installed and discovered, normal requests only need the user's intent and material.
+
 ## Identity
 
 `yusijia auth login --json` opens the site's authorization page. The user signs in
 and approves there. `auth status --json` shows the bound account and expiry. Default
 site is https://yusijia.me; use explicit `--site` for a different HTTPS site or local
-development loopback. State the site/account before any content plan. `auth logout`
+development loopback. Never infer a development site from cwd, browser tabs or a
+beta version. For an explicitly requested development trial, keep a separate HOME
+for CLI credentials/progress and private plans, pass the same explicit `--site` on
+every site command, and keep a short task-local environment/progress note without
+secrets. Do not use production credentials or fall back to production when local
+requests fail. State the site/account before a CLI remote-write plan. Plain
+conversational drafting or local analysis does not require login or a site query.
+`auth logout`
 revokes then removes this site's credential. A failure is not successful revocation.
 The credential lasts 30 days and is plaintext in an owner-only file, not encrypted;
 same-user processes, root and copied files remain a risk.
 
 ## Read And Prepare
 
+- Inspect the actual images using the host's local image tools, plus available EXIF
+  and auxiliary material. If visual tools are unavailable, disclose that limitation
+  and use metadata conservatively; do not describe rule grouping as seeing images.
+- Separate visible observations, metadata/document facts and the user's account.
+  A ticket is not proof that every booked leg was traveled; its screenshot date is
+  not the trip date. Do not invent identities, relationships, feelings or stories.
+- Photo-first: a general request to organize supplied material should propose
+  selected photos and an existing or new album, not a checklist of every feature.
+  Query relevant albums and ask only when a core choice cannot be safely made.
+- Growth timeline entries are for meaningful milestones established by the user or
+  clarified with them, not routine itineraries or every scene. Do not infer a first
+  ride or developmental achievement from a photo. Omit events without such meaning.
+  A vague request to record material does not itself request a timeline event.
+- Do not draft or save a diary unless the user expresses that intent. A family
+  photo request alone is not diary consent; diary capability remains available.
+- Merge questions only about facts indispensable to the selected content, such as
+  its event date or milestone meaning. Missing people, feelings or itinerary details
+  are not a mandatory questionnaire. Polish expression, not facts. If sources
+  conflict, clarify the affected claim or omit it; continue unrelated photo/album
+  preparation. Omit uncertain optional content rather than blocking the workflow.
+
 - Query only relevant bounded pages: `photos|albums|timeline|diary list --limit 30
   --cursor <opaque-cursor> --json`; `get --id <id> --json` for detail.
 - Photo URLs are omitted by default. Only request `photos get --id <id>
@@ -35,6 +75,10 @@ same-user processes, root and copied files remain a risk.
   first. Do not imply rule-based grouping is visual inspection, or that old photos
   without hashes can all be deduplicated. Never scan the whole disk or call external
   vision services by default. Keep generated plans/scans private.
+- Do not trim or re-encode a readable supported original just to bypass a CLI
+  rejection. Report the incompatibility and preserve the original; any necessary
+  conversion needs a disclosed separate copy and user approval, not silent loss
+  of original hashes or auxiliary information.
 
 ## Preview, Confirm, Execute
 
@@ -54,9 +98,10 @@ In a combined plan, `albums.photos` requires both `payload.add` and
 values or references to a prior album action). For a standalone association,
 prefer `albums add/remove --id ... --photo-id ... --out ...`.
 
-Before execution show the site, account, every target and expected version, selected
-photos including GPS/time and create/reuse expectations, album associations, event
-date/title/description/photos, and complete diary text plus DRAFT/PUBLISHED status.
+Before execution show only the content actually proposed: site, account, every
+target and expected version, selected photos including GPS/time and create/reuse
+expectations and album associations; for requested events include date/title/
+description/photos, and for requested diaries include complete text and status.
 Ask the user to confirm that exact plan. One explicit confirmation may cover the
 whole plan. A saved draft is also a remote write requiring confirmation.
 
@@ -91,4 +136,5 @@ already published photos remain. Do not delete formal content as compensation.
 `skills update` synchronizes registered installations without overwriting edits.
 `update` uses public npm for this global package, then the new CLI synchronizes
 Skills. Do not run sudo, read secret files, or claim success on a Skill conflict.
-The private placeholder package cannot update remotely until publication preflight.
+The public package is `@yuchaocheng/yusijia`. Beta installations update from the
+`beta` tag; stable installations use `latest`, with no fallback between channels.