prompt-profile 0.2.1 → 0.2.2

package/README.md

@@ -59,7 +59,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

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));
@@ -7999,7 +8083,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 +8141,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 +14422,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.2";
 // src/cli/render-error.ts
 /** How to fix an InvalidArgument, per flag. */
 const ARGUMENT_HINTS = {
@@ -14578,6 +14663,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 +15040,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.2",
   "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",