Arquitectura de Información

1. Propósito y alcance

Esta sección define cómo se organiza el conocimiento del área: qué tipos existen, dónde vive cada uno, cómo se clasifican y las reglas que impiden que se duplique o se desactualice. Es doctrina del modelo — aplica a toda app de Prism, no a una en particular.

Delimitación: el detalle físico de esta plataforma de documentación (el script de sync, los tiers de publicación, los workflows, las credenciales de Gitea) es la Capa B de la app 000-dev-ops-model y vive en su docs/internal/plataforma-documentacion/architecture.md; esta sección lo referencia, no lo reproduce. El ciclo del contexto está en 02 §4; el status.md y su rol entre sesiones, también en 04 §8.

2. La regla de separación

El conocimiento del área se organiza según una regla única:

Los hechos con estructura viven en SeaTable; el conocimiento narrativo vive en Git; nada se duplica.

La duplicación es el enemigo: toda copia se desactualiza por diseño y reintroduce el problema original que el modelo existe para resolver (antipatrón A6). Donde la narrativa necesita un hecho estructurado —un servidor, una API, el estado de una tarjeta— lo referencia en SeaTable, no lo copia.

3. Las tres capas — clasificación por alcance

El conocimiento se clasifica en tres capas. La capa no es una carpeta ni algo que una app posee: es el alcance del conocimiento. A qué aplica un documento determina su capa, no dónde está guardado.

Capa	Qué conocimiento es	Alcance	Dónde vive
A — Organizacional	El modelo operativo (secciones 00–11), políticas de desarrollo, convenciones, decisiones cross-app	Toda el área (transversal)	Git · `docs/internal/` del repo que lo aloja
B — Por aplicación	`architecture.md`, notas de módulo, decisiones fechadas (`decisions/`), integraciones (`integrations.md`) de una app	Una app específica (local)	Git · `docs/internal/` + `docs/agent/` del repo de esa app
C — Estado operativo	Tarjetas, criterios congelados, resultados de QA, desviaciones, notas de sesión efímeras, inventario (apps, servidores, APIs, automatizaciones)	Los hechos vivos del momento	SeaTable

Reglas de mantenimiento por capa:

A y B (Git): cambian por Pull Request; todo archivo lleva front-matter (title, owner, last_verified, sources, version). Son narrativa verificada por humanos.
C (SeaTable): las notas efímeras expiran con la tarjeta; solo entran a la Base durable por el ritual de promoción (P4). La Capa B referencia los registros de SeaTable, nunca los copia.

La distinción A/B es conceptual, no física. Todo el conocimiento narrativo —de alcance de área o de app— vive en docs/ de su repo; lo que lo hace Capa A o Capa B es a quién aplica, no en qué carpeta está. No hay una carpeta “Capa A” y otra “Capa B”.

3.1 El caso del repo `000-dev-ops-model`

Este repo aloja conocimiento de ambos alcances, y por eso es especial:

El modelo operativo (secciones 00–11) es Capa A: todo lo que se decide ahí aplica a todas las apps.
La arquitectura de la plataforma (architecture.md: su sync, sus tiers, su build) es Capa B: aplica solo a esta app.

No se mezclan ni se confunden — coexisten, cada uno con su clasificación, porque este repo tiene la particularidad de ser a la vez el hogar del conocimiento transversal y una app con su propia documentación técnica. Es la consecuencia natural de que la clasificación sea por alcance: un mismo repo puede contener conocimiento de más de un alcance.

4. El estado de despliegue — `status.md`

Hay un tipo de conocimiento que no encaja limpio en las tres capas: el estado de despliegue transversal a una app — el delta staging↔main, las ramas protegidas, la migración vigente, las variables de entorno por sitio. No es Capa C (no vive en SeaTable ni es por-tarjeta) ni Capa B (no es narrativa durable). Es efímero pero vive en Git, y se documenta aparte por eso.

El status.md de cada app es el puente de estado entre sesiones: lo escribe /wrap-up al cerrar (⑥), lo lee /start al abrir. Vive en la raíz del repo, fuera de docs/, por dos razones que apuntan al mismo sitio: es global a la app y no es documentación de la Base; y su autor es el Developer, cuyo carril de escritura excluye docs/ (03 §7.5).

Cuatro reglas lo gobiernan:

Es efímero y se verifica contra el sistema vivo, no es fuente durable. Una línea del status.md es una pista de dónde mirar, no evidencia — el sistema vivo manda. Esto lo salva del antipatrón del diario (A2): no pretende ser verdad, es una foto que se vuelve a tomar.
El estado por-tarjeta vive en SeaTable (Capa C), nunca aquí. El status.md es solo lo transversal a la app que el board no modela.
Lo durable que aparezca aquí se promueve. Una decisión sobre migraciones que hoy esté en el status.md migra a decisions/ de la Capa B; el status.md es tránsito, no destino.
Es el canal por el que viaja una corrección de documentación. Cuando un Developer detecta un dato erróneo en la Base, no edita docs/ —está fuera de su carril—: lo registra aquí, y ⑦ Publisher lo aplica al conciliar el release, porque ya recibe el status.md como entrada (03 §7.5.3).

(Su rol en el ciclo del contexto y la mecánica de /start·/wrap-up: 04 §8. Su ubicación está decidida —la raíz del repo—; la forma exacta y la cadencia de actualización con varios Developers en paralelo siguen siendo detalle de implementación — decisión abierta D11.)

5. Generación de vistas humanas

Toda la documentación de cara al humano se genera desde la Base de Conocimiento; ninguna vista se edita a mano.

La vista técnica del sitio la concilia ⑦ Publisher desde la Base, al publicar.
Las guías de usuario, guiones de tutorial y mensajes de novedades los genera ⑧ User Guide & Comms, usando como fuente principal el verification criteria verificado contra staging: los casos de prueba verificados constituyen, por construcción, el paso a paso real de uso de cada funcionalidad.

Ambos productos pasan por revisión humana (L1) antes de publicarse. La relación fuente→vista es la misma que un documento fuente y el PDF que se exporta de él: la fuente siempre gana; la vista se regenera.

6. Ubicación del contenido — `docs/` vs. tooling

Todo el contenido navegable —las secciones del modelo (Capa A) y la documentación de cada app (Capa B)— vive en docs/ de su repo, uniforme con todos los repos. Lo que se sincroniza al sitio es siempre docs/; no hay carpetas de contenido con otro nombre.

El tooling accionable que otros repos jalan para operar bajo el modelo —skills de agentes, hooks, plantillas de artefactos— no es documentación del sitio: es código/config. Vive en su propia carpeta de herramientas, fuera del flujo de docs, y no entra al sync.

La regla mnemotécnica, en dos preguntas:

¿Entra un programador nuevo? → se lee el modelo en docs/internal/. Es lectura humana; docs/internal/ forma personas.
¿Se hace onboarding de una app nueva? → el repo jala el tooling que mantiene la consistencia. Es consumo por máquina/repo; el tooling equipa repos.

6.1 El eje que decide el destino es la audiencia

Dentro de docs/ de cada app, dos ejes ortogonales deciden a dónde va cada archivo:

Audiencia (destino humano), por carpeta.
Ingesta de agentes, por flag de front-matter: agent: true suma un archivo al corpus; todo docs/agent/** entra siempre. No es una audiencia humana: es el otro eje.

La audiencia no es “interno” frente a “externo”. Esa distinción se rompe en el primer caso real: un empleado de Prism que usa una app es su usuario, no parte del equipo que la construye. La audiencia es la calidad en la que la persona actúa, y una misma persona puede estar en dos: en Vendor Portal, un empleado que carga sus datos para que le paguen actúa como proveedor; el mismo empleado, aprobando una orden de compra en el admin, actúa como colaborador.

Las audiencias son una lista cerrada, y son los tres tipos de rol de Core Identity — para que la documentación y la autenticación no tengan vocabularios paralelos:

Carpeta	Audiencia	Quién es
`docs/internal/`	Equipo	Tecnología: el modelo operativo y la documentación técnica
`docs/public/<iface>/` → `collaborators`	Colaboradores	Empleados que usan la app
`docs/public/<iface>/` → `vendors`	Proveedores	Proveedores
`docs/public/<iface>/` → `customers`	Clientes	Clientes
`docs/agent/`	—	No es audiencia: es el eje de ingesta de agentes

Ampliar la lista es una decisión explícita del Director; el gate rechaza cualquier audiencia que no esté declarada.

La audiencia es propiedad del documento, no de la app. Por eso no se declara una vez por repo: dentro de docs/public/ hay una carpeta por interfaz —con el nombre que esa interfaz tiene en el código— y el docs/_meta.yml de la app mapea cada interfaz a su audiencia:

audiences:
  portal: vendors                        # una interfaz, una audiencia
  admin: collaborators
  common: [collaborators, customers]     # pantalla común: dos audiencias

Una pantalla que sirve a dos audiencias es un documento de dos audiencias: se declara con una lista y el build lo publica en los dos portales. Y al contrario: los módulos que solo usa el equipo interno de una app quedan fuera del portal de clientes por construcción, no por permisos.

Tres reglas de integridad, que el gate hace cumplir:

No existe documento público sin audiencia declarada. Una interfaz que no esté en el mapa detiene el build.
No existe audiencia inventada. Un valor fuera de la lista cerrada detiene el build.
Una carpeta de tier que nadie va a alimentar no se crea. Un public/ vacío en un repo sin usuarios es una invitación a poner ahí lo que no va.

El mapa de audiencias repo por repo, con su justificación, está en la página 06a.

6.2 Cómo se entra y qué está protegido

La documentación de usuario se entra desde dentro de la app: cada app lleva un botón de help desk que apunta a su sección en el portal de la audiencia correspondiente. Eso tiene dos consecuencias.

La primera es de diseño, y es la razón de fondo para hacerlo así: pone la documentación en el punto donde ocurre el trabajo. Es el mismo principio que funda todo el modelo —el conocimiento almacenado donde el trabajo no ocurre se muere (§2 de la sección 02)— aplicado al lado del usuario final en vez de al del equipo.

La segunda es de autenticación: la sesión se hereda. El usuario llegó desde una app donde ya estaba autenticado con Core Identity, así que los portales no resuelven login propio. De ahí la regla de protección, que es una sola:

La documentación de acceso es abierta; las secciones de cada app son cerradas.

La documentación de acceso —qué es este portal, cómo entro, cómo recupero mi cuenta— es propiedad del repo de Core Identity, que es quien gobierna la autenticación. Es pre-login y la misma para las tres audiencias, así que su _meta.yml la mapea a la lista completa y el build la copia a los tres portales: es la sección abierta de cada uno. Todo lo demás exige sesión.

El límite de la protección es la audiencia, no la asignación. Las asignaciones de Core Identity gobiernan el acceso a las apps; dentro de un portal, cualquiera con sesión de esa audiencia ve toda su documentación. No es una simplificación por comodidad: un sitio estático publica el mismo HTML y el mismo índice de búsqueda para todos, así que filtrar por usuario exigiría una capa dinámica — y un buscador que muestra títulos que no se pueden abrir revela justo lo que pretende ocultar. El corolario es útil: si un contenido es demasiado sensible para toda su audiencia, la señal es que no pertenece a esa audiencia.

6.3 `content/` es un destino generado, nunca fuente

El sitio se sirve desde una carpeta content/ que el build regenera desde cero juntando el docs/ de todas las apps, ruteado por audiencia. Está en .gitignore, nadie la edita a mano, y no puede desincronizarse: si un repo cambia, el siguiente build la reconstruye. Para el repo central, que es su propia fuente y a la vez el sitio, el sync no es redundante — su trabajo real es la agregación multi-repo; por eso nada se escribe a mano en content/, el build lo borraría.

7. Reglas transversales

Fecha y fuente en todo dato. Todo archivo de la Base declara last_verified y sources; el contenido más antiguo que el umbral se entrega marcado como no verificado (P3). El gate docs-lint rechaza un .md sin los cinco campos de front-matter obligatorios.
Corrección obligatoria. Contexto erróneo detectado → corregir la fuente es obligación inmediata (aprox. 5 minutos), no backlog.
Credenciales. Los agentes y workflows transmiten el enlace de 1Password; en ningún caso obtienen, almacenan o reproducen el secreto (A8 / E5).
Independencia de herramienta. El conocimiento durable vive en Git y SeaTable, nunca cautivo en la herramienta de publicación (Starlight), el board (SeaTable) o el proveedor de IA — son capas intercambiables sobre contenido portable (02 §7 A8, sección 08).

8. Relación con el resto de la documentación

Para conocer	Sección
El ciclo del contexto y cómo el `Plan` ensambla el conocimiento	02 §4
El `status.md` en el ciclo y los comandos `/start`·`/wrap-up`	04 §8
Qué agente genera y mantiene cada vista	04
Dónde interviene cada capa en el flujo de una tarjeta	05
Qué tiers lleva cada repo y por qué	06a · Mapa de documentación por repo
El detalle físico de esta plataforma (sync, tiers, build, credenciales)	`plataforma-documentacion/architecture.md`
El régimen de PR, promoción, corrección e independencia de herramienta	08

Historial de versiones

Versión	Fecha	Cambio
v2.1	2026-09-04	§4: el `status.md` se ubica en la raíz del repo, fuera de `docs/` — es global a la app y su autor es el Developer, cuyo carril excluye `docs/`. Cuarta regla: es el canal por el que viaja una corrección de documentación hasta ⑦.
v2.0	2026-09-03	El eje de destino pasa de tier a audiencia. “Interno vs. externo” se retira: se rompe en el primer caso real, porque un empleado que usa una app es su usuario y no parte del equipo. La audiencia es la calidad en que la persona actúa, es propiedad del documento y no de la app, y se declara por interfaz en el `_meta.yml` de cada repo; una pantalla común es un documento de dos audiencias. Lista cerrada alineada a los tres tipos de rol de Core Identity (`collaborators`, `vendors`, `customers`), sin vocabulario paralelo al de la autenticación. Nuevo §6.2: la documentación se entra desde dentro de la app, la sesión se hereda, la documentación de acceso (propiedad de Core Identity) es la sección abierta de cada portal, y el límite de protección es la audiencia y no la asignación —con el porqué técnico. §6.3 renumerada.
v1.3	2026-09-03	§6.1: la regla de quién lleva `public/` se explicita — la frontera es quien usa la app frente a el equipo que la construye, no dentro frente a fuera de la empresa. Se referencia la página 06a con el mapa por repo.
v1.2	2026-09-03	Rutas actualizadas: el contenido del modelo pasa a `docs/internal/modelo-operativo/` (primer módulo de la documentación) y el `architecture.md` de esta app a `docs/internal/plataforma-documentacion/`.
v1.1	2026-09-03	Referencia a `architecture.md` reapuntada tras su renumeración (§4 y §5).
v1.0	2026-09-03	Versión inicial a nivel de consulta 1A. Reescribe el Anexo B del T0. Capas A/B/C definidas como clasificación por alcance (área/app/estado), no por posesión ni por carpeta; la distinción A/B es conceptual, no física. Caso especial del repo 000 (aloja Capa A + su Capa B). `status.md` como estado de despliegue transversal (fuera de las tres capas). Ubicación `docs/internal/` vs. tooling; modelo de tres tiers y flag `agent:true`; `content/` generado. Referencia a `architecture.md` para lo físico, sin duplicar. Reglas transversales (fecha/fuente, corrección, credenciales, independencia de herramienta). Front-matter YAML; destino `docs/internal/`.