{"record":{"id":"ebfc0a0f00521e30","repo":"windmill-labs/windmill","slug":"kept-existing-f-f-name-hand-written-not-t","errorCode":null,"errorMessage":"Kept existing f/${f}/${name} (hand-written — not the generated pointer)","messagePattern":"Kept existing f/(.+?)/(.+?) \\(hand-written — not the generated pointer\\)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"cli/src/commands/pipeline/docs.ts","lineNumber":287,"sourceCode":"  // file that merely references `@PIPELINE.md` alongside its own content.\n  const written = [\"PIPELINE.md\"];\n  const pointers: Array<[string, string]> = [\n    [\"AGENTS.md\", `See @PIPELINE.md for this pipeline's graph, assets, and how to run it.\\n`],\n    [\"CLAUDE.md\", `Instructions are in @PIPELINE.md\\n`],\n  ];\n  for (const [name, content] of pointers) {\n    const p = path.join(folderDir, name);\n    if (existsSync(p)) {\n      let existing: string;\n      try {\n        existing = readFileSync(p, \"utf-8\");\n      } catch {\n        continue;\n      }\n      // Anything other than our exact generated pointer is treated as\n      // hand-written and preserved (writing when identical is a no-op anyway).\n      if (existing.trim() !== content.trim()) {\n        log.warn(\n          colors.yellow(`Kept existing f/${f}/${name} (hand-written — not the generated pointer)`),\n        );\n        continue;\n      }\n    }\n    await writeFile(p, content, \"utf-8\");\n    written.push(name);\n  }\n  log.info(colors.green(`✓ Wrote ${written.join(\", \")} to f/${f}`));\n}\n","sourceCodeStart":269,"sourceCodeEnd":298,"githubUrl":"https://github.com/windmill-labs/windmill/blob/e474e8803ce2ff5c2df09a58dab51d45f5c922ca/cli/src/commands/pipeline/docs.ts#L269-L298","documentation":"During `wmill pipeline docs` generation (generatePipelineDocs), each generated doc file is written as a pointer into Windmill. If an existing file on disk contains anything other than that exact generated pointer, it is treated as hand-written documentation and left untouched, with this warning. Generation never overwrites human edits.","triggerScenarios":"Running docs generation when f/<flow>/<name> docs already exist locally and their content differs from the generated pointer (someone edited the file, or it predates the pointer scheme).","commonSituations":"A teammate wrote custom Markdown docs for a flow; docs were generated by an older CLI version with a different pointer format; the file was partially hand-edited after generation.","solutions":["If the hand-written content is what you want, do nothing — the file is intentionally preserved.","If you want the generated pointer back, delete the local file (or restore the pointer text) and rerun the docs generation.","Diff the file against a freshly generated pointer to decide which version to keep.","Keep hand-written docs out of the generation output path so generation and authorship don't fight."],"exampleFix":"# before: generation warns and keeps your edits\nwmill pipeline docs  # -> Kept existing f/myflow/docs (hand-written ...)\n# after: regenerate from scratch\nrm f/myflow/docs.md && wmill pipeline docs","handlingStrategy":"validation","validationCode":"// detect hand-edited docs before generating\nimport { readFileSync, existsSync } from 'fs';\nconst p = 'f/myflow/docs.md';\nif (existsSync(p)) {\n  const existing = readFileSync(p, 'utf-8').trim();\n  if (!existing.startsWith('<docs-pointer')) {\n    console.warn(`${p} is hand-written; generation will keep it`);\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never hand-edit files in the generated docs output path; author docs elsewhere.","Commit generated pointers so teammates don't diverge.","Diff before/after a generation run to spot preserved files.","Regenerate from a clean tree when unsure which version is canonical."],"tags":["docs","code-generation","cli","file-conflict"],"backgroundTag":"generated-file-overwrite-skipped","analyzedSha":"e474e8803ce2ff5c2df09a58dab51d45f5c922ca","analyzedAt":"2026-09-03T12:38:19.024Z","contentChangedAt":"2026-09-03T12:38:19.024Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}