sinkra-os

Instalador do framework SINKRA (LOCAL layer) para alunos do cohort. Um comando instala o sistema de pipeline + forja no seu projeto, preservando o que é seu.

Acesso restrito a alunos ativos do cohort. O conteúdo é servido sob demanda após validação do seu email — não há repositório público nem conteúdo no pacote npm.

Pré-requisitos

• Node.js 18+ (node --version)
• Um diretório de projeto (idealmente um repositório git)
• Seu email de aluno ativo no cohort

Instalação

No diretório do seu projeto:

npx sinkra-os install

O instalador vai:

1. Pedir seu email (ou use --email [email protected], ou a env SINKRA_EMAIL).
2. Validar que você é um aluno ativo (caso contrário, acesso negado).
3. Baixar o bundle do framework e aplicá-lo no diretório atual.

Ao final, você terá:

• CLAUDE.md com a seção do framework (no topo; seu conteúdo abaixo é preservado)
• .claude/skills/ — pipeline SINKRA + forja (sinkra-create-skill) + advisors
• .claude/agents/ — agentes do pipeline e da forja
• .claude/rules/ — regras canônicas do framework
• .sinkra/ — config, registries e templates
• .sinkra/install-manifest.json — registro do que foi instalado

Atualização

npx sinkra-os update

Antes de um sync, limpeza ou projeção em um repositório com .sinkra/, a ferramenta DEVE consultar .sinkra/install-manifest.json. Um path presente em files é gerenciado pelo SINKRA e não deve ser removido nem sobrescrito. Veja o contrato do install manifest.

Baixa a versão mais recente e re-aplica preservando suas customizações. Se já estiver na versão atual, não faz nada. Respeita o arquivo .hub-sync-ignore (veja abaixo).

Diagnóstico

npx sinkra-os doctor

Verifica a integridade: arquivos presentes, edições locais em arquivos do framework (que serão restauradas no próximo update), seção gerenciada do CLAUDE.md, merges manuais pendentes e a resolvibilidade das deps de runtime (veja abaixo).

Dependências de runtime das skills

Os scripts das skills SINKRA validam os artefatos que você produz — sinkra-output.json (via AJV strict) e os companions YAML. Para isso eles fazem require('ajv'), require('ajv-formats') e require('js-yaml') em tempo de execução. Essas não são dependências do instalador sinkra-os — são deps de runtime que precisam resolver no ambiente onde as skills rodam.

Como isso é provisionado:

• Install global (via AIOX Cockpit): as 3 deps já são provisionadas pelo mecanismo de provisioning global (sinkra-deps + NODE_PATH) — nada a fazer. Formalizado em ADR-COCKPIT-GLOBAL-SKILLS-PROVISIONING (repo aiox-cockpit).
• Install de projeto (npx sinkra-os install): hoje o requisito é diagnosticado, não auto-provisionado. Rode npx sinkra-os doctor — ele executa require.resolve de ajv, ajv-formats, js-yaml e ajv/dist/2020 a partir do seu projeto e, se alguma faltar, emite um WARN advisório nomeando a dep faltante + como resolver (garantir um node_modules resolvível com essas deps, ex.: NODE_PATH apontando para um, ou instalá-las num node_modules do caminho de resolução do Node). O WARN não bloqueia — o doctor continua reportando saúde normalmente.

Débito deferido (auto-provisão): a materialização automática dessas deps no install/update de projeto foi deliberadamente deferida (decisão YAGNI). O gatilho de resgate é um aluno real bloqueado no install de projeto sem as deps. O racional completo (determinismo via lockfile, circularidade de resolução do NODE_PATH, vendor-tarball vs npm-fetch, offline/air-gapped, SOT neutro de pinning) está em ADR-SINKRA-OS-RUNTIME-DEPS-GUARANTEE §7 (repo synkra-hub).

Dependências de SISTEMA dos fluxos /referencia e /pesquisa

Os fluxos de referência (funil de ingestão de conhecimento: cursos, vídeos, repos, páginas, PDFs → acervo buscável) e pesquisa têm dependências fora do Node. O SOT é system-deps.json (empacotado com o CLI), e o npx sinkra-os doctor sonda cada uma (advisory — nomeia a falta e o porquê, sem bloquear a instalação):

| Fluxo | Precisa | Por quê | |-------|---------|---------| | /referencia | git, ffmpeg, yt-dlp, python 3 | clone de repos, extração de áudio, aquisição de mídia, scripts de web/STT | | /referencia | pip install -r .sinkra/services/etl/requirements.txt | scrapling==0.2.99 (pin obrigatório — 0.4.x quebra) + faster-whisper (STT local $0) | | /referencia | Node.js ≥ 18 | índice local portátil em .sinkra/acervo/index.json, com content hash, busca lexical e roteamento; sem node:sqlite | | /referencia (opcional) | Calibre + pandoc | só a rota ebook_epub; sem eles, os demais profiles operam normalmente | | /pesquisa | lanes MCP docker-gateway:EXA + mcp:scrapling | resolvem na sessão do agente — sem binário local; a sonda real é o testConnection() dos scripts de lane |

Ao atualizar uma instalação que ainda tenha .sinkra/acervo/acervo.db, preserve o arquivo legado e execute node .sinkra/services/etl/bin/acervo.mjs index para reconstruir a projeção JSON a partir de .sinkra/knowledge-factory/*/raw/*.md. O runtime nunca apaga o banco legado automaticamente.

Workspace Sinkra e MCP são extensões opcionais: sem eles, /referencia conclui S07/S08 em local_only. A mensagem explica que ambos são pré-requisitos da camada remota, mas que a escrita remota só é habilitada depois que o writer também estiver provisionado e atestado. Busca vetorial/RRF não faz parte desse piso local.

Como suas customizações são preservadas

O instalador faz merge por seção gerenciada, nunca sobrescreve cego:

| O que | Como é tratado | |-------|----------------| | CLAUDE.md | Seção do framework no topo (entre marcadores SINKRA-FRAMEWORK:BEGIN/END); seu conteúdo abaixo é intocado. | | .claude/settings.json, package.json, .sinkra/registries/*.json | Deep-merge: chaves do framework atualizadas, suas chaves preservadas. | | .claude/rules/, .claude/agents/, .claude/skills/sinkra-*/ | Arquivos do framework (instalados/atualizados). | | Suas skills (.claude/skills/<nome> sem prefixo sinkra-) | Nunca tocadas. | | .claude/hooks/ existentes | Hook seu é preservado; a versão do framework é salva como <hook>.sinkra-v<N> para você comparar. | | .gitignore | Append-only (só adiciona linhas que faltam). | | .sinkra/state/, workspace/ | Nunca tocados (seu trabalho). |

.hub-sync-ignore (opt-out)

Crie um arquivo .hub-sync-ignore na raiz para excluir caminhos do update (um padrão por linha):

.claude/rules/uma-regra-que-eu-customizei.md

Opções

| Flag | Efeito | |------|--------| | --email <e> | Email do aluno (ou env SINKRA_EMAIL, ou prompt). | | --dir <path> | Diretório alvo (default: diretório atual). | | --force | Permite downgrade da seção gerenciada (raro). |

Solução de problemas

| Mensagem | O que fazer | |----------|-------------| | email não é de um aluno ativo do cohort | Confirme seu email de matrícula / status ativo. | | não foi possível contatar o servidor de licença | Verifique sua conexão e tente de novo. | | doctor reporta arquivos ausentes | Rode npx sinkra-os install novamente. | | merge manual necessário | Compare seu hook com o .sinkra-v<N> gerado ao lado. | | doctor: deps de runtime NÃO resolvíveis | Garanta um node_modules resolvível com ajv/ajv-formats/js-yaml (ex.: NODE_PATH, ou instale-as no caminho de resolução). Veja "Dependências de runtime das skills". |

SINKRA-OS — EPIC-187. Suporte: canal do cohort.