prompt-profile 0.2.1 → 0.2.3

package/README.md

@@ -6,13 +6,19 @@ collaborate with AI. Uses your logged-in `claude` or `codex` CLI: no API key nee
 **Analysis sends selected, redacted prompts to your CLI's model service and uses your
 subscription quota.** Reports and analysis caches stay on your computer.
 
-![Fictional sample share card](https://erictsai83.github.io/prompt-profile/sample-card.png)
+![Maintainer collaboration profile](https://erictsai83.github.io/prompt-profile/owner-example/card.en.png)
 
-[Full report](https://erictsai83.github.io/prompt-profile/sample-report.html)
-· [Shareable report](https://erictsai83.github.io/prompt-profile/demo/without-personal/report.html)
+[My report](https://erictsai83.github.io/prompt-profile/owner-example/report.html)
+· [繁體中文卡片](https://erictsai83.github.io/prompt-profile/owner-example/card.png)
+· [Fictional example](https://erictsai83.github.io/prompt-profile/sample-report.html)
 · [Template gallery](https://erictsai83.github.io/prompt-profile/demo/templates/index.html)
 
-All examples use fictional data.
+The card above is my personal analysis from November 1, 2026, rendered with the current
+code. The public report omits prompt quotes, project names and custom instruction names.
+Ability scores describe supported practice in my conversations, not population ranks;
+the API estimate is not my subscription bill. The separate fictional examples and gallery
+are generated from the latest repository code.
+[View the latest README on GitHub](https://github.com/EricTsai83/prompt-profile#readme).
 
 ## Quick start
 
@@ -59,7 +65,9 @@ for extraction and macOS setup.
 - **PNG share cards**: a 1200 × 630 card per language, without prompt quotes.
 - **`profile.json`**: the data used to render the report again without another analysis.
 - **Local history**: successful analyses are kept in a report library; open the output folder's
-  `index.html` to browse them.
+  `index.html` to browse them. Generated output includes a `README.md` explaining each file,
+  backups, deletion and index repair; an existing user README is preserved. New report folders use readable local timestamps, for example
+  `2026-11-01_03-12-04+0800-<id>` (`+0800` is the UTC offset). Older report folders remain readable.
 
 Reports support English and Traditional Chinese; quotes stay in their original language.
 The default is English, or both languages on a Chinese system locale. Each extra language
@@ -68,9 +76,9 @@ A Chinese-only request stops if translation still fails; it does not substitute
 
 Observations cite verified prompt quotes, but quote matching and model review do not prove an
 interpretation is correct. Small histories may show “Early observations” instead of a role.
-The [radar](docs/ability-scores.md) assesses six AI collaboration abilities from verified quotes in these conversations. Scores describe supported practice, not psychological traits or population ranks; “not assessed” is not a low score.
+The [radar](https://github.com/EricTsai83/prompt-profile/blob/main/docs/ability-scores.md) assesses six AI collaboration abilities from verified quotes in these conversations. Scores describe supported practice, not psychological traits or population ranks; “not assessed” is not a low score.
 
-New analyses also retain [reusable instruction provenance](docs/instruction-provenance.md): what a skill is documented to do, who selected it for the task, and which historical requirements were supplied.
+New analyses also retain [reusable instruction provenance](https://github.com/EricTsai83/prompt-profile/blob/main/docs/instruction-provenance.md): what a skill is documented to do, who selected it for the task, and which historical requirements were supplied.
 
 ## Usage
 
@@ -99,7 +107,7 @@ printed retry command: completed chunks and merges are cached; later steps may u
 
 Each analysis saves calls, retries, cache reuse, token coverage and cost provenance, including
 failed executions. The report shows generation usage separately from historical activity.
-See [execution accounting](docs/execution-accounting.md) for recovery, unknown measurements
+See [execution accounting](https://github.com/EricTsai83/prompt-profile/blob/main/docs/execution-accounting.md) for recovery, unknown measurements
 and cost-threshold limits.
 
 ## How much a run uses
@@ -207,8 +215,8 @@ source prompts can be in any language.
 
 ## Development
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, checks and releases, and
-[AGENTS.md](AGENTS.md) for architecture and repository rules.
+See [CONTRIBUTING.md](https://github.com/EricTsai83/prompt-profile/blob/main/CONTRIBUTING.md) for setup, checks and releases, and
+[AGENTS.md](https://github.com/EricTsai83/prompt-profile/blob/main/AGENTS.md) for architecture and repository rules.
 
 ## License
 

package/dist/bin.js

@@ -1493,7 +1493,7 @@ const ChunkObservations = Schema.Struct({
 	})).pipe(Schema.withDecodingDefaultKey(Effect.succeed([])))
 });
 // src/domain/Library.ts
-const RUN_ID = /^(?:\d{8}T\d{6}Z-[a-f0-9]{32}|legacy-[a-f0-9]{32})$/u;
+const RUN_ID = /^(?:(?:\d{8}T\d{6}Z|\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}[+-]\d{4})-[a-f0-9]{32}|legacy-[a-f0-9]{32})$/u;
 const Count = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
 const Iso = Schema.String.check(Schema.makeFilter((s) => /^\d{4}-\d\d-\d\dT/u.test(s) && Number.isFinite(Date.parse(s))));
 const RunManifest = Schema.Struct({
@@ -2288,6 +2288,83 @@ const readAsset = (name, locate) => new Uint8Array(readFileSync(locate()));
 * `$XDG_CACHE_HOME/prompt-profile`, else `~/.cache/prompt-profile` (macOS too).
 */
 const resolveCacheDir = (env, home, path) => path.join(env["XDG_CACHE_HOME"] || path.join(home, ".cache"), "prompt-profile");
+// src/platform/output-guide.ts
+const MARKER = "<!-- Generated by prompt-profile: output guide -->";
+const GUIDE = `${MARKER}
+# Your prompt-profile output
+
+Open **index.html** to browse completed reports, newest first. Inside a report
+folder, open **report.html** directly. Both work offline without a server.
+Only files relevant to the commands you ran will be present.
+
+## What the files mean
+
+| File or folder | Purpose |
+| --- | --- |
+| index.html | The report library: start here to find the latest report. |
+| reports/<timestamp>-<id>/ | One completed analysis. Each new analysis gets its own folder. |
+| reports/legacy-<id>/ | A preserved report from an older output layout. |
+| report.html | The readable report, with a language switch when available. |
+| card.png | The summary image in the report's first language. |
+| card.<language>.png | Additional language images, such as card.en.png. A missing card does not mean the HTML report failed. |
+| profile.json | The analysis data. Keep this to render supported profiles again without another LLM analysis. Older formats may require the package version that created them. |
+| run.json | Completion metadata: time, engine, languages, coverage and card status. Keep with the completed report. |
+| render.json | Rendering choices, version, profile fingerprint and relative source path. |
+| variants/<name>/ | Alternative renders. Each contains its own report, profile, rendering metadata and available cards. Rendering the same variant again replaces its generated files. |
+| library.json | Rebuildable catalog of completed reports; it is not the analysis itself. |
+| executions/<id>/summary.json | Execution status, call accounting and recovery information, including failed or interrupted runs. These are separate from completed reports. |
+| stats.json | Statistics-only output from the stats command; replaced the next time stats uses this folder. |
+| plan.json and chunks/ | Dry-run estimate and redacted text prepared for analysis. Use a separate output folder for each dry run; later runs may leave older chunks. |
+| README.md | This generated guide. Your own existing README is left untouched. |
+
+## Dates and names
+
+New analysis folders use the computer's local time, for example
+2026-11-01_03-12-04+0800-<id>: November 1, 2026 at 03:12:04, UTC+08:00.
+The final ID prevents collisions. Older names such as 20261031T191204Z-<id>
+use UTC (Z); they represent the same instant in this example. JSON timestamps
+remain in machine-readable formats. The library orders reports by completion
+time, so use index.html rather than sorting mixed old and new folder names.
+
+## Keep, move or delete
+
+- Back up or move the whole output folder to preserve relative links. Copy a
+  complete report folder when archiving one analysis; its link back to the library
+  needs the original surrounding layout. Do not rename report folders or edit IDs.
+- To remove an analysis, delete its whole folder under reports/, including any
+  variants you no longer need. This permanently removes that saved analysis.
+  Never delete profile.json or run.json alone from a report you want to keep.
+- After deleting reports, rebuild index.html and library.json without an LLM call:
+
+      prompt-profile history --out "<output-folder>"
+
+- Unwanted variants, stats.json, dry-run plan.json and chunks/ can be deleted
+  independently. Keep profile.json if you want to render a variant again.
+- Execution folders can be deleted independently when their diagnostics are no
+  longer needed. Deleting them does not remove completed reports or the separate
+  analysis cache; keep them while troubleshooting an interrupted run.
+- Hidden reports/.pending-* folders are unfinished output. Remove them only after
+  confirming that no prompt-profile process is using this output folder.
+- Older root-level report files and variants may have been copied to a legacy
+  archive. Remove originals only after verifying that the archived copies match.
+
+These files contain personal analysis and may include prompt excerpts, local paths
+or redacted input. Review the files you choose to share. Render and history commands
+work locally; neither requires another LLM analysis. No saved report history is
+pruned automatically.
+`;
+/** Refresh our generated guide without replacing user notes or following README symlinks. */
+const writeOutputGuide = (root) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const file = path.join(root, "README.md");
+	const info = yield* fs.lstat(file).pipe(Effect.catchIf(isNotFound$1, () => Effect.succeed(null)));
+	if (info !== null) {
+		if (info.type !== "File" || info.size > 64000n) return;
+		if (!(yield* fs.readFileString(file)).startsWith(`${MARKER}\n`)) return;
+	}
+	yield* writePrivateFile(fs, path, file, GUIDE);
+}).pipe(Effect.mapError(toFileError(root)));
 // src/platform/executions.ts
 const ID = /^[0-9a-f-]{36}$/u;
 /** `<root>/executions`, never a symlink. */
@@ -2331,6 +2408,7 @@ const createExecution = (root, startedAtMs) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const folder = yield* directory(root, true);
+	yield* writeOutputGuide(root);
 	const id = randomUUID();
 	yield* fs.makeDirectory(path.join(folder, id), { mode: 448 });
 	const initial = {
@@ -2422,7 +2500,12 @@ const reportsDirectory = (root, create) => Effect.gen(function* () {
 });
 const createStage = (root) => Effect.gen(function* () {
 	const reports = yield* reportsDirectory(root, true);
-	const id = `${(/* @__PURE__ */ new Date()).toISOString().replace(/[-:]/gu, "").replace(/\.\d{3}Z$/u, "Z")}-${randomUUID().replaceAll("-", "")}`;
+	const now = /* @__PURE__ */ new Date();
+	const pad = (value) => String(value).padStart(2, "0");
+	const date = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+	const time = `${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`;
+	const offset = -now.getTimezoneOffset();
+	const id = `${`${date}_${time}${`${offset >= 0 ? "+" : "-"}${pad(Math.floor(Math.abs(offset) / 60))}${pad(Math.abs(offset) % 60)}`}`}-${randomUUID().replaceAll("-", "")}`;
 	const directory = (yield* Path.Path).join(reports, `.pending-${id}`);
 	yield* (yield* FileSystem.FileSystem).makeDirectory(directory, { mode: 448 });
 	return {
@@ -2461,6 +2544,7 @@ const scan = (root) => Effect.gen(function* () {
 const repair = (root, render) => Effect.gen(function* () {
 	const path = yield* Path.Path;
 	yield* reportsDirectory(root, true);
+	yield* writeOutputGuide(root);
 	for (let attempt = 0; attempt < 32; attempt++) {
 		const index = yield* scan(root);
 		yield* write(path.join(root, "library.json"), json(index));
@@ -4402,7 +4486,7 @@ const productDark = (bg) => ({
 });
 const CLASSIC = {
 	id: "classic",
-	version: 36,
+	version: 37,
 	color: {
 		light: {
 			bg: "#f6f6f3",
@@ -5079,7 +5163,7 @@ const fontsOf = (theme) => {
 /** Color tokens of a classic or product card. */
 const schemeOf = (theme) => theme.color[theme.card.scheme];
 /** The archetype name, headline and trait chips of a classic or identity card. */
-const identityCopy = (profile, theme, hide, lang, showGraphic, colors, badge = null, width) => {
+const identityCopy = (profile, theme, hide, lang, showGraphic, colors, badge = null, width, period = null) => {
 	const c = contentIn(profile, lang);
 	const card = theme.card;
 	const font = fontsOf(theme);
@@ -5112,6 +5196,12 @@ const identityCopy = (profile, theme, hide, lang, showGraphic, colors, badge = n
 			marginTop: card.headline.gap,
 			color: colors.muted
 		}, clip(c.headline, 120)),
+		period === null ? null : h("div", {
+			fontSize: card.size.header,
+			color: colors.muted,
+			marginTop: card.headline.gap,
+			flexShrink: 0
+		}, period),
 		hide.includes("traits") ? null : h("div", {
 			display: "flex",
 			gap: card.chips.gap,
@@ -5217,7 +5307,6 @@ const CLASSIC_RADAR = {
 */
 const classicTree = (profile, theme, hide, lang, showUsage, exactDates, avatar) => {
 	const k = schemeOf(theme);
-	const card = theme.card;
 	const showGraphic = !hide.includes("graphic");
 	return h("div", {
 		width: CARD_WIDTH,
@@ -5234,31 +5323,24 @@ const classicTree = (profile, theme, hide, lang, showUsage, exactDates, avatar)
 		muted: k.muted,
 		value: k.accent,
 		card: k.card
-	}, !hide.includes("traits")) : [], copyLayer(theme, [
-		h("div", {
-			display: "flex",
-			justifyContent: "flex-end",
-			alignItems: "center"
-		}, [hide.includes("stats") ? null : h("div", {
-			fontSize: card.size.header,
-			color: k.muted
-		}, cardPeriod(profile, lang, exactDates))]),
-		identityCopy(profile, theme, showGraphic ? [...hide, "traits"] : hide, lang, showGraphic, {
-			muted: k.muted,
-			chip: {
-				color: k.accent,
-				backgroundColor: k.accentSoft
-			}
-		}, avatar && showGraphic ? roleBadge(avatar, lang, {
-			fg: k.fg,
-			border: k.border
-		}) : null, showGraphic ? 520 : void 0),
-		h("div", {
-			display: "flex",
-			flexDirection: "column",
-			gap: 18
-		}, [metricRow(profile, theme, hide, lang, k.muted, showUsage), cardFooter(profile, theme, hide, lang, k.muted, showUsage, exactDates)])
-	])]);
+	}, !hide.includes("traits")) : [], copyLayer(theme, [h("div", {
+		display: "flex",
+		flex: 1,
+		alignItems: "center"
+	}, [identityCopy(profile, theme, showGraphic ? [...hide, "traits"] : hide, lang, showGraphic, {
+		muted: k.muted,
+		chip: {
+			color: k.accent,
+			backgroundColor: k.accentSoft
+		}
+	}, avatar && showGraphic ? roleBadge(avatar, lang, {
+		fg: k.fg,
+		border: k.border
+	}) : null, showGraphic ? 520 : void 0, hide.includes("stats") ? null : cardPeriod(profile, lang, exactDates))]), h("div", {
+		display: "flex",
+		flexDirection: "column",
+		gap: 18
+	}, [metricRow(profile, theme, hide, lang, k.muted, showUsage), cardFooter(profile, theme, hide, lang, k.muted, showUsage, exactDates)])])]);
 };
 /** A share-first look: identity colors, display type and the activity graphic. */
 const identityTree = (profile, theme, hide, lang, showUsage, exactDates, avatar) => {
@@ -7999,7 +8081,7 @@ const cardFileName = (lang, isDefault) => isDefault ? "card.png" : `card.${lang}
 const noCjkFonts = Effect.fail(new FontUnavailable({ reason: "no CJK font available" }));
 /**
 * Write `report.html`, `profile.json` and one card per language into `outDir` (overwriting
-* only those files). A card failure never fails the report. Every render also writes
+* only generated files, including README.md). A card failure never fails the report. Every render also writes
 * `render.json`: its options and the profile it came from (`source`, relative to `outDir`).
 */
 const writeReport = (profile, outDir, options = DEFAULT_RENDER_OPTIONS, source = null, cjkFonts = noCjkFonts) => Effect.gen(function* () {
@@ -8057,6 +8139,7 @@ const writeReport = (profile, outDir, options = DEFAULT_RENDER_OPTIONS, source =
 			error: "reason" in e ? e.reason : e.message
 		}))));
 	}
+	yield* writeOutputGuide(outDir).pipe(Effect.mapError((e) => new Error(e.detail)));
 	const first = cards[0];
 	return {
 		html,
@@ -14337,7 +14420,7 @@ const analyze = (input) => Effect.gen(function* () {
 * Package version. Injected by tsdown at build time; during development and tests
 * (tsx / vitest) it falls back to reading package.json.
 */
-const VERSION = "0.2.1";
+const VERSION = "0.2.3";
 // src/cli/render-error.ts
 /** How to fix an InvalidArgument, per flag. */
 const ARGUMENT_HINTS = {
@@ -14578,6 +14661,7 @@ const writeDryRun = (p, outDir, context, voice = DEFAULT_VOICE) => Effect.gen(fu
 		}))
 	};
 	yield* writeFileOrFail(path.join(outDir, "plan.json"), `${JSON.stringify(summary, null, 2)}\n`);
+	yield* writeOutputGuide(outDir);
 });
 /**
 * The plan a CLI reports wins over the hint from local files; the file's extra detail is kept.
@@ -14954,8 +15038,10 @@ const runStats = (options) => Effect.gen(function* () {
 	yield* out.line("");
 	const collected = yield* readSources;
 	const { stats } = yield* runPipelineStep(collected, options.since);
-	const file = path.join(yield* resolveOut(options.out), "stats.json");
+	const root = yield* resolveOut(options.out);
+	const file = path.join(root, "stats.json");
 	yield* writeFileOrFail(file, `${JSON.stringify(encodeStats(stats), null, 2)}\n`);
+	yield* writeOutputGuide(root);
 	const peak = peakHour(stats);
 	const percent = (x) => Math.round(x * 100);
 	yield* out.line("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prompt-profile",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Read your Claude Code / Codex prompt history locally, analyse it with your logged-in claude or codex CLI, and generate a personal profile report.",
   "keywords": [
     "ai",