In-repo docs, AGENTS.md files and how we keep them from going stale
View All Tags
The question: The product-name rule is about site conversion. Can the docs simply name AI products, tools, agents and WordPress plugins?
The question: the measurement tools had grown to ten files. Were they duplicating each other, or conflicting? And if so, should the overlapping ones be merged?
The question: Is it better to make a design-decision permalink https://docs.unysonplus.com/block-enrichment-which-types-stay-core — flattened to the site root — instead of https://docs.unysonplus.com/decisions/block-enrichment-which-types-stay-core?
The question: The Element Mapping tables classify every shortcode option as native / via-CSS / unmapped. Accordion showed 18 unmapped — which looks like the converter is failing. Is a high unmapped count a problem to drive to zero? Should we hand-author “pre-mapping” data, or do we need a pile of real sites to map everything properly?
The question: UnysonPlus has a large PHP surface — ~845 public-prefixed helper functions and ~350 actions/filters. Is it wise to document all of it, the way people mean when they say "document every function"? And if so, how — hand-written pages, or generated?
The question: The Site Converter's conversion knowledge lived in two places — a deep
how-it-works (architecture + algorithm) under the extension docs, and a conceptual how-it-works
(capture-first → outside-in → measure) under the AI Dev Kit — and neither was clearly the canonical
home. Should we move all the extension's conversion subpages into the AI Dev Kit and reduce the
extension section to a basic overview + a link, so all conversion info lives in one place?
The question: The framework's biggest reputational liability is the inherited "Unyson is outdated" perception. A technology audit of the plugin showed that's largely stale for this fork. Should we publish a public Technology page to rebut it — and if so, how do we handle the fact that such a page also has to acknowledge the remaining legacy?
The question: We want the docs site to explain how the deterministic Site Converter turns a
source element into a UnysonPlus shortcode — the Priority / Recognizer / Matches when / Becomes
table, plus the native options each mapping sets. Two open questions: where does it go — a row
added to each /docs/shortcodes/<element> page, or one consolidated table — and do we hand-write
it or generate it?
The question: we already decided the converter's job is to fix the algorithm, not the output. But in practice, when a build hits a section the converter can't map yet (e.g. a WooCommerce product grid), what is the exact, repeatable iteration — and when do you actually write a recognizer versus just hand-build it?
The question: every no-code post type builder has the same objection sitting under it — now my content schema depends on your plugin. It is a fair objection. Do we answer it with documentation, or with a feature?
The question: Should other developers using the AI Dev Kit have their agents change the Site Converter — and if we instead want them to report improvements back, is GitHub the right place, given not everyone has an account?
The question: Should the kit's theme-settings-reference.md go deeper — documenting every
preset's options and all their choices — and split into a folder, one file per main tab?
The question: Would it help to add a markdown file to each option-type folder in
framework/includes/option-types?