README

Vault do AppStock

Documentação viva do projeto, em notas atômicas ligadas entre si. Mora dentro do repo, em Markdown puro: você edita no Obsidian, eu edito no Claude Code, é o mesmo arquivo.

Esta é a Onda 1 (piloto) — só a fatia de onboarding da organização. Se o formato agradar, as demais ondas seguem o mesmo molde. O documento extenso docs/APPSTOCK-PROJETO.md continua como reserva até ser drenado para cá.

Ver online (sem instalar nada)

https://docs-dev.appstock.com.br — o vault publicado como site, com busca, backlinks automáticos e grafo interativo. Abre no celular também.

O site se reconstrói sozinho: salvou um arquivo em docs/vault/, em ~20 segundos está no ar. Quem publica é o contêiner appstock-dev-docs (ops/docs-site/), que monta o vault read-only e chama o Quartz.

Duas diferenças em relação ao Obsidian, e são de propósito:

	Obsidian	Site
Dataview	executa ao vivo	pré-renderizado no build (ver abaixo)
Canvas	interativo	vira texto — .canvas não existe no site
Edição	sim	não (leitura). Edite no Obsidian, pelo GitHub ou peça ao agente.

Consultas no site: o marcador gerado

O Dataview só roda dentro do Obsidian. Para uma consulta aparecer também no site, ponha um comentário HTML logo antes do bloco (o Obsidian ignora comentário):

| Área | Pronto | Parcial | Mockup | 501 | Falta |
|---|---|---|---|---|---|
| plataforma | 0 | 9 | 0 | 0 | 0 |

No build, o bloco é substituído pela tabela equivalente. Bloco sem marcador vira um aviso no site — nunca código cru. Geradores disponíveis: placar, fases, atencao, envelhecendo, decisoes, lista-fluxos, backlinks, fase-itens:<n>. Para criar outro, veja ops/docs-site/dataview.mjs.

Como abrir

1. Obsidian → Open folder as vault → aponte para docs/vault/.
2. Instale os plugins da comunidade (Settings → Community plugins):

Plugin	Para quê
Dataview	Motor de tudo. Transforma o frontmatter em consulta — placar, checklists e progresso deixam de ser escritos à mão.
Tasks	Checkbox com prazo/prioridade, consultável em todo o vault.
Kanban	Board de fase lendo as mesmas notas.

3. Ative Settings → Dataview → Enable JavaScript Queries (algumas consultas usam).
4. Recomendado: Settings → Editor → Show line numbers off, e o local graph fixo na barra lateral direita. O graph global é bonito e inútil; o local, de 1–2 saltos, é o que se navega.

.obsidian/ fica fora do git (é config de máquina). Ver .gitignore do repo.

Como está organizado

docs/vault/
├── _index.md          ← comece aqui: placar e navegação, gerados
├── _esquema.md        ← contrato de frontmatter (leia antes de criar nota)
├── _mapas/            ← Canvas: o mapa visual das articulações
├── fases/             ← as fases do projeto (suas)
├── fluxos/            ← jornadas ponta a ponta
├── telas/             ← 1 nota por tela
├── modulos/           ← 1 nota por módulo de backend
├── entidades/         ← 1 nota por conceito de dado
└── decisoes/          ← ADRs: por que as coisas são como são

Nomes têm prefixo (tela-, mod-, ent-, flx-, adr-) porque o Obsidian resolve [[link]] por nome de arquivo, e sem prefixo telas/signup colidiria com modulos/signup. Nos textos, use link com rótulo: [[mod-signup|módulo de signup]].

As regras (valem para nós dois)

1. Uma nota = uma coisa. Se a nota trata de duas, são duas notas.
2. Não repita texto — ligue. Se você está reexplicando o que é um espelho, é porque falta um [[ent-bancos]] ali.
3. Status mora no frontmatter, nunca só na prosa. É o que faz o placar existir.
4. Todo fato tem endereço. arquivo.py:linha ou nada — a nota descreve o código, não o desejo.
5. verificado_em é sagrado. Ao confirmar (ou corrigir) uma nota contra o código, atualize a data. Nota com data velha é suspeita, não mentira.
6. Lacuna vira checkbox, na nota da fase. Não crie nota separada para cada lacuna pequena.

Convenção de status

Valor	Significa
pronto	Funciona ponta a ponta: tela + endpoint + dado.
parcial	Existe com buraco relevante.
mockup	Tela existe, dado é fixo ou a ação não persiste.
bloqueado	Endpoint responde 501 — desligado de propósito na virada standalone.
falta	Não existe.
na	Não se aplica (decisões, entidades).