Páginas de conocimiento frente a páginas personalizadas

Qué es esto

ComStack tiene dos tipos de páginas editables mediante las herramientas MCP, y elegir el editor incorrecto es el error más común al empezar. Esta página explica cómo el servidor clasifica una página como knowledge (conocimiento) o custom (personalizada), qué herramienta edita cada una y las medidas de seguridad que impiden una edición entre tipos. (Existe una tercera superficie —el agente de voz en vivo—, pero no se edita como una página).

Cómo funciona

Cada documento expone un page_type de knowledge o custom, devuelto en cada entrada en vivo/borrador de get-project-state y en get-page-content. El servidor lo deriva; nunca se establece el page_type directamente:

custom cuando metadata.type es "custom" o el documento utiliza la plantilla custom-page.
knowledge en cualquier otro caso (el valor predeterminado).

El tipo se asigna uno a uno a un editor:

page_type	Qué es	Editar con	Forma del cuerpo
`knowledge`	Markdown en una plantilla estructurada (docs, blog, producto, FAQ…)	`create-page` / `update-page`	Markdown en `content`
`custom`	Astro/HTML con libertad total de diseño	`upload-custom-page`	`body_source` opaco + marcadores `<T>` / `data-t-key`

La protección es de tipo “fall-closed” (bloqueo por defecto) en ambas direcciones:

update-page en una página custom es rechazada: ”… es una página CUSTOM (metadata.type=“custom”). Edítala con upload-custom-page (body_source + marcadores <T key=…>), no con update-page. update-page solo edita páginas de conocimiento (markdown).”
upload-custom-page en una página knowledge es rechazada con el código de error wrong_tool_knowledge_page: ”… es una página KNOWLEDGE (markdown), no una página personalizada. upload-custom-page sobrescribiría su cuerpo con body_source opaco. Edítala con update-page o elige un slug diferente para la página personalizada.”

Por lo tanto, lee el page_type antes de elegir una herramienta.

Cuándo usarlo

Al decidir qué herramienta edita una página existente según su URL.
Al elegir una plantilla para una nueva página (estructura markdown frente a libertad total de diseño).
Al diagnosticar un rechazo por wrong_tool_*.

Tipo de página frente a plantilla

page_type es general; elige el editor. La plantilla del documento es específica; elige los campos y la estructura. Una página knowledge sigue eligiendo una plantilla (technical-doc-page, blog-post, solution-page, …), cada una con sus metadatos requeridos; una página custom siempre utiliza la plantilla custom-page. Lista las plantillas mediante get-project-state.available_doc_templates; inspecciona una con get-doc-template.

Ejemplo

get-page-content(project_id, slug: 'pricing', language: 'en')
  -> { page_type: 'knowledge', path: '...', metadata: { ... }, content: '## ...' }

(knowledge -> markdown editor)
update-page(project_id, slug: 'pricing', content: '## ...')        (accepted)

(the same call on a custom page is refused:)
update-page(project_id, slug: 'home-hero')
  -> InvalidRequest: 'home-hero' is a CUSTOM page (metadata.type="custom").
     Edit it with upload-custom-page ...

Errores comunes

update-page en una página personalizada — rechazada con una redirección a upload-custom-page. Vuelve a realizar la edición como una carga de página personalizada o confirma si te referías a una página diferente.
upload-custom-page en una página de conocimiento (wrong_tool_knowledge_page) — sobrescribiría el markdown con código fuente opaco. Usa update-page o elige un nuevo slug para la página personalizada.
Asumir que page_type es editable — se deriva de metadata.type / la plantilla. Para hacer que una página sea custom, créala a través de upload-custom-page; no puedes cambiar una página de conocimiento existente configurando un campo.

Relacionado

Guía de inicio — dónde se sitúa la selección del tipo de página en el flujo.
Páginas personalizadas — creación de páginas personalizadas de principio a fin.
Publicación — cómo ambos tipos de página gestionan borradores y promociones.
Catálogo de herramientas — update-page frente a upload-custom-page.
Errores — las protecciones contra herramientas incorrectas en la lista completa de errores.