manuales-factorpesca/references/estructura.md

# Estructura del documento

Anatomía obligatoria de cualquier manual generado por esta skill. Omite o añade secciones solo si el usuario lo pide explícitamente.

## Visión general

```
1. Portada
2. Índice
3. Resumen ejecutivo
4. Requisitos previos
5. Capítulo 1
6. Capítulo 2
...
N. Solución de problemas
N+1. Glosario (opcional)
N+2. Aviso de propiedad y confidencialidad (obligatoria)
```

## 1. Portada

Elementos obligatorios:

- Logo de FactorPesca (placeholder hasta que se sustituya por el definitivo).
- Eyebrow en accent color (por defecto «Manual de usuario»).
- Título del manual: "Manual de [Aplicación]".
- Subtítulo descriptivo de una línea.

La portada es deliberadamente minimalista: solo logo, eyebrow, título y
subtítulo. Sin versión, fecha de emisión, autor ni metadatos.

Plantilla HTML: la primera página dentro de `templates/manual.html` con clase `cover`. Forzar `break-after: page` en `@media print`.

## 2. Índice

- Generado automáticamente por `manual.js` a partir de los `h1`, `h2`, `h3` del documento.
- Numeración con líderes de puntos (CSS `leader`).
- Mostrar solo `h1` y `h2` por defecto. Si un capítulo tiene muchas sub-secciones, incluir `h3` discretamente con sangrado.
- Numeración: capítulos en romanos (I, II, III), secciones en arábigos (1.1, 1.2).

## 3. Resumen ejecutivo

- Una página con tres bloques:
  1. **Objetivo**: para qué sirve el manual y qué aprenderá el lector.
  2. **Audiencia**: a quién va dirigido (operadores, supervisores, administradores, etc.).
  3. **Alcance**: qué procesos cubre y qué procesos quedan fuera.

Si el manual es muy largo (>40 páginas), dividir el resumen en "objetivo" y "cómo leer este manual".

## 4. Requisitos previos

Lista de todo lo que el lector necesita antes de empezar:

- **Software**: navegador, sistema operativo, plugins.
- **Cuenta**: tipo de usuario y permisos necesarios.
- **Datos**: archivos, credenciales o recursos de entrada.
- **Conocimientos**: formación previa recomendada.

Estructura como `.checklist` o `.data-table` con dos columnas ("Requisito", "Detalle").

## 5. Capítulos (núcleo del manual)

Un capítulo por proceso de usuario. Estructura interna:

1. **Encabezado del capítulo** (`<h1 data-chapter>`)
2. **Objetivo del capítulo** (caja `.callout-info` con título "Objetivo").
3. **Pasos** (cada uno un `.step-block`).
4. **Resultado del proceso** (caja `.callout-tip` con título "Resultado final").
5. **Errores comunes** (caja `.callout-warning` con título "Errores comunes"), si aplica.

Reglas:

- Un capítulo describe un proceso completo. Si el proceso es muy largo, dividirlo en varios capítulos, pero numerarlos con un prefijo común (4.1, 4.2, 4.3).
- El primer paso de cada capítulo debe incluir una captura del estado inicial (pantalla previa).
- El último paso debe mostrar el estado final con un callout `tip` "Resultado final".
- Evitar capítulo con más de 12 pasos. Si los hay, dividir.

## 6. Solución de problemas

Apartado obligatorio. Estructura:

```html
<section id="troubleshooting">
  <h1>Solución de problemas</h1>
  <p>Si encuentra algún error, busque el síntoma en esta sección antes de contactar al soporte.</p>

  <article class="trouble">
    <h3 class="trouble-symptom">No puedo iniciar sesión</h3>
    <p><strong>Causa probable:</strong> la cuenta está bloqueada tras tres intentos fallidos.</p>
    <p><strong>Solución:</strong> espere 15 minutos o solicite el desbloqueo al administrador.</p>
  </article>
  ...
</section>
```

Cada problema: síntoma, causa, solución. Como máximo cinco problemas por bloque; si hay más, agrupar por categoría con `<h2>`.

## 7. Glosario (opcional)

Tabla de dos columnas: término, definición. Incluir solo si el manual usa jerga técnica o nombres propios.

## 8. Aviso de propiedad y confidencialidad (obligatoria)

Última página del manual. Su propósito es reforzar visualmente que el
documento es **propiedad privada de FactorPesca S.A. de C.V.** y
establecer las restricciones de uso, reproducción y divulgación.

Elementos obligatorios:

- Marca `©` grande en la parte superior.
- Razón social completa: `FactorPesca S.A. de C.V.`
- Subtítulo "Todos los derechos reservados."
- Título centrado: "Aviso de propiedad y confidencialidad".
- Cinco párrafos numerados en lenguaje formal que cubran:
  1. Propiedad intelectual sobre todos los elementos del documento.
  2. Prohibición de reproducción, distribución y transformación sin
     autorización escrita.
  3. Carácter privado y confidencial de la información, y obligación
     de devolución o destrucción al término de la relación.
  4. Reconocimiento de marcas registradas de terceros.
  5. Ausencia de garantía y limitación de responsabilidad.
- Caja de contacto (callout primario) con el correo del área legal:
  `legal@factorpesca.com`.
- Pie pequeño con la atribución de la skill y la tipografía usada.

Sin cabecera ni pie de página (clase `no-chrome` y named page
`copyright`). El borde superior de 6pt en color primary marca la
transición desde el contenido del manual hacia el cierre legal.

## Numeración y jerarquía

- Capítulos: `I`, `II`, `III`...
- Secciones: `1.1`, `1.2`, `2.1`...
- Sub-secciones: `1.1.1`, `1.1.2`...
- Pasos: numeración global con círculo de accent (`1`, `2`, `3`...). No reiniciar en cada capítulo.
- Figuras: `Figura 1.`, `Figura 2.`... (auto-numeradas por `manual.js`).
- Tablas: `Tabla 1.`, `Tabla 2.`... (auto-numeradas por `manual.js`).

## Saltos de página

- `h1` siempre en página nueva (`break-before: page`).
- `h2` puede fluir, pero nunca quedar al final de la página (`break-after: avoid` en el heading + `break-before: avoid` en el primer párrafo).
- Ningún `.step-block` puede partirse a la mitad (`break-inside: avoid`).
- Una figura o tabla debe vivir entera en la misma página, salvo que sea muy alta: en ese caso, el caption se imprime en ambas páginas.

## Encabezados y pies

Configurados en `manual.css` con `@page` Paged Media. Cada página muestra:

- Cabecera: nombre del capítulo actual (eyebrow small caps).
- Pie izquierda: "FactorPesca · Manual de usuario de [Aplicación]".
- Pie derecha: "Página X de Y".

Las páginas marcadas con `.no-chrome` (portada, aviso de propiedad) ocultan cabecera y pie.