diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0f96130..e09e7e9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,6 +18,8 @@ flatpak install --user flathub org.gnome.Platform//51 # once make start-flatpak ``` +New to developing inside the GNOME SDK? Justin's [Building GNOME Apps with Rust, Part 1: Getting Started](https://fromthearchitect.dev/posts/gnome-rust-part-1-getting-started/) walks through the setup; the toolchain differs, the runtime workflow is the same. + ## Ground rules - **Core stays headless.** `gknowledge/core/` must not import GTK. UI code lives in `gknowledge/ui/`. diff --git a/DISTRIBUTING.md b/DISTRIBUTING.md index 0436e65..587bf34 100644 --- a/DISTRIBUTING.md +++ b/DISTRIBUTING.md @@ -296,7 +296,7 @@ Il percorso seguente "ripercorre i passi" dei progetti studiati nell'ordine in c ## 8. Registro dei canali e delle ricerche già fatte -> **Aggiornato al 14 ottobre 2026.** Questa sezione evita di ripetere le stesse indagini: elenca dove gknowledge è già stato proposto, con quale esito, quali piattaforme coprono i competitor e quali ricerche non hanno prodotto nulla. Prima di cercare nuovi canali, aggiornare questa sezione. I testi pronti da incollare sono in [`docs/launch/`](docs/launch/) (`directories.md`, `outreach.md`, `blog-post.md`, `zh.md`, `emerging.md`). +> **Aggiornato al 14 ottobre 2026; il punto al 19 ottobre è in §10.** Questa sezione evita di ripetere le stesse indagini: elenca dove gknowledge è già stato proposto, con quale esito, quali piattaforme coprono i competitor e quali ricerche non hanno prodotto nulla. Prima di cercare nuovi canali, aggiornare questa sezione. I testi pronti da incollare sono in [`docs/launch/`](docs/launch/) (`directories.md`, `outreach.md`, `blog-post.md`, `zh.md`, `emerging.md`). ### 8.1 Stato delle candidature @@ -310,7 +310,7 @@ Il percorso seguente "ripercorre i passi" dei progetti studiati nell'ordine in c | OpenAlternative | directory | 14 ott 2026 | **non inviata**: servono 250★ per repo con meno di 6 mesi (50★ dal 7 gen 2027) e un sito su dominio proprio; le schede gratuite escono una al giorno lavorativo | riprovare con `gknowledge.io` attivo | | EveryDev.ai | directory di AI dev tools (c'è OpenKnowledge) | 14 ott 2026 | login GitHub fatto; serve completare l'onboarding del profilo prima di `/create/tool` | completare onboarding, poi compilare con `directories.md` | | ClaudeKit (claudekit.io) | sito coreano curato a mano di strumenti per Claude Code (c'è nashsu) | 14 ott 2026 | **non raggiungibile**: nessun form, repo o contatto | nessuno | -| dev.to | articolo | 13 ott 2026 | [pubblicato](https://dev.to/francescobianco/i-turned-karpathys-llm-wiki-into-a-native-gnome-app-and-it-works-offline-130c). 17 ott: [commento di Justin (@fromthearchitect)](https://dev.to/fromthearchitect/comment/3i4d5), data/AI architect su Fedora che sta scrivendo un'app foto GNOME in Rust. Ha messo la stella; il `.deb` e `install.sh` non gli servono e chiede il Flatpak (non ha visto il remote su Pages: badge e tabella del README dicevano ancora "Flatpak planned"). Consiglia di sviluppare nel runtime GNOME e osserva che le pagine invecchiano per drift delle sorgenti, non per allucinazioni. Da qui nascono il controllo "stale sources" e `make start-flatpak` (PR #42, mergiato il 19 ott; il PR #43 corregge il click nella sidebar) | **rispondergli quando il Flatpak è verificato** su una distro non Ubuntu: ringraziare punto per punto, dargli la riga `flatpak install`, chiedergli di provarlo su Fedora, chiedere il permesso di linkare la sua guida al GNOME SDK in CONTRIBUTING, invitarlo sulla issue delle stale pages. Più avanti: cross-promozione tra app GNOME e, se il rapporto cresce, co-maintainer per il packaging (§6). Ripubblicare su Medium con canonical a dev.to | +| dev.to | articolo | 13 ott 2026 | [pubblicato](https://dev.to/francescobianco/i-turned-karpathys-llm-wiki-into-a-native-gnome-app-and-it-works-offline-130c). 17 ott: [commento di Justin (@fromthearchitect)](https://dev.to/fromthearchitect/comment/3i4d5), data/AI architect su Fedora che sta scrivendo un'app foto GNOME in Rust. Ha messo la stella; il `.deb` e `install.sh` non gli servono e chiede il Flatpak (non ha visto il remote su Pages: badge e tabella del README dicevano ancora "Flatpak planned"). Consiglia di sviluppare nel runtime GNOME e osserva che le pagine invecchiano per drift delle sorgenti, non per allucinazioni. Da qui nascono il controllo "stale sources" e `make start-flatpak` (PR #42, mergiato il 19 ott; il PR #43 corregge il click nella sidebar) | **risposto il 19 ott** dall'utente, dopo il rilascio della 0.3.0 con il Flatpak; ringraziato anche nell'[annuncio della 0.3](https://github.com/orgs/openapi/discussions/72). **Lui ha risposto la sera del 19 ott** ([commento](https://dev.to/fromthearchitect/comment/3ia9i)): apprezza `stale_sources` via MCP e il fix WAL/document portal, autorizza il link alla [Parte 1](https://fromthearchitect.dev/posts/gnome-rust-part-1-getting-started/) della sua serie (aggiunto in CONTRIBUTING il 20 ott), proverà il Flatpak su Fedora 44 in settimana e aprirà issue (GitHub `justinf555`): smistarle per prime. Facoltativo: un breve "thanks, linked!" su dev.to. Più avanti: cross-promozione tra app GNOME e, se il rapporto cresce, co-maintainer per il packaging (§6). Ripubblicare su Medium con canonical a dev.to | | Theo James (Medium, editor di *Better Workflow*) | classifica "8 Apps… Karpathy-Style LLM Knowledge Base" | 14 ott 2026 | testo pronto in `outreach.md` (risposta all'articolo o pitch alla pubblicazione); nessun contatto esterno | inviare da account Medium | | Prahlad G. Menon (themenonlab.blog) | blog che ha coperto Tolaria e OKF | 14 ott 2026 | email pronta in `outreach.md` (prahlad.menon@quant.md) | inviare | | awesome-gnome (1.622★, c'è Newelle) | lista awesome | — | **saltata**: richiede release stabili mature | proporre dopo Flathub | @@ -477,3 +477,64 @@ Il messaggio per questo pubblico è **offline, senza API a pagamento, su un port **Stima.** Con tutto il piano, la somma dei valori centrali è circa **+80–110 stelle**. Senza Show HN scende a **+45–70**: le 100 in 8 settimane diventano improbabili senza HN o un giorno in trending. L'alternativa a puntare tutto su HN è la combinazione Reddit + 48 ore concentrate. **Non conviene:** Lobsters (invito), altre liste awesome piccole, pubblicità, giveaway (vietati). + +## 10. Rilancio dopo la v0.3.0 (19 ottobre 2026) + +### 10.1 Cosa dicono davvero le statistiche + +| Giorno | Clone (unici) | Run di CI | Visite (unici) | +|---|---|---|---| +| 12 ott | 2 (2) | — | 1 (1) | +| 13 ott | 304 (81) | 39 | 42 (6) | +| 14 ott | 139 (61) | 4 | 11 (3) | +| 15 ott | 94 (41) | 5 | 9 (4) | +| 16 ott | 68 (32) | 3 | 46 (19) | +| 17 ott | 20 (15) | — | 4 (3) | +| 18 ott | 12 (9) | — | 6 (3) | + +Fonti: `gh api repos/openapi/gknowledge/traffic/clones`, `/traffic/views`, `gh run list`. + +- **I clone non misurano le persone.** Ogni `actions/checkout` conta come clone, e ogni runner come clone "unico". Il picco del 13 coincide con le 39 run di CI di quel giorno (v0.2.1, v0.2.2, i pacchetti `.deb`, il repository APT e il remote Flatpak); il calo segue la fine dei rilasci, non una perdita di pubblico. A questi si aggiungono mirror e scraper che clonano i repo appena entrano in una lista awesome. Da qui in avanti la metrica di riferimento sono **visite uniche e stelle**, non i clone. +- **Il traffico umano è sempre stato basso**: 3–6 visitatori unici al giorno, con due picchi, il 13 (articolo dev.to) e il 16 (pubblicazione su PyPI e sul registro MCP, 19 unici). Referrer in 14 giorni: github.com 8 unici, alternativeto.net 3, Google 2, news.ycombinator.com 2. +- **Stelle: 19** (15 al 15 ott). Le 4 nuove arrivano dalle liste awesome e dall'articolo dev.to (justinf555 il 17 ott è con ogni probabilità Justin di dev.to, che ha detto di aver messo la stella). Il primo contributo esterno di AdityaWagh06 (#1, #19) arriva da up-for-grabs o awesome-for-beginners. +- **Nessuna delle candidature in attesa si è mossa**: awesome-for-beginners #2143, awesome-hacktoberfest-2026 #22, ollama #19001 e awesome-context-engineering #88 sono aperte senza commenti; HelloGitHub #3956, ruanyf #12333 e OpenGithubs #33 non hanno risposte. awesome-mcp-servers #16968 e #16969 hanno l'etichetta `missing-glama`: il bot chiede la scheda su Glama e il badge di punteggio nella riga. +- **Il §9.5 si è fermato alla preparazione**: fatti topic, homepage e pacchetto MCP; nessuna delle azioni "utente" (Show HN, Reddit, social, TWIG, outreach) è partita. Il traffico è finito con l'ultima azione fatta. + +### 10.2 Perché adesso + +La v0.3.0, uscita oggi, è il primo rilascio con un **Flatpak installabile su qualsiasi distribuzione** (`io.github.openapi.Gknowledge`, remote su Pages) e una funzione con un nome riconoscibile ("pagine che invecchiano quando la fonte cambia"). È esattamente il gancio che §6 (Fase 2) e §9.5 (azione 6) aspettavano per TWIG e Phoronix, e toglie l'obiezione "solo Ubuntu" dallo Show HN. + +### 10.3 Sequenza + +Calendario: TWIG esce il venerdì, gli item vanno inviati entro giovedì. Lo Show HN resta uno solo (§8.5, §9.4) e va fatto con l'app installabile ovunque. + +| Quando | Azione | Chi | Testo | +|---|---|---|---| +| lun 19 – mar 20 ott | Rispondere a Justin su dev.to: Flatpak uscito, riga `flatpak install`, chiedergli di provarlo su Fedora (piano in §8.1) | utente | da scrivere insieme | +| lun 19 – mar 20 ott | Scheda su Glama per `openapi/gknowledge` (il `glama.json` c'è già), poi badge nelle PR #16968 e #16969 | utente (login Glama), noi (badge) | — | +| mer 21 ott | Discussions attive, annuncio della 0.3.0 lì (§9.5 azione 13); link incrociati dai README di openapi-skills, openapi-python-sdk e mcp-server (azione 10) | noi | — | +| entro gio 22 ott | **Item TWIG** per la 0.3.0 nella stanza Matrix `#thisweek:gnome.org` | utente | `docs/launch/README.md` | +| gio 22 – ven 23 ott | Segnalazione a Phoronix e OMG! Ubuntu; articolo di aggiornamento su dev.to ("0.3: now on any distro via Flatpak, and pages that know when their source changed") | utente | `docs/launch/README.md` | +| settimana del 19 | 3–5 commenti veri su thread HN di LLM wiki o LLM locali; karma Reddit | utente | — | +| ~~mar 27 o mer 28 ott~~ | ~~Show HN~~: sostituito dal post HN del 19 ott (§10.4). Thread X/Mastodon e post LinkedIn aziendale restano, in un giorno a scelta | utente | `docs/launch/README.md` (aggiornato alla 0.3) | +| giorno dopo | r/LocalLLaMA e r/ObsidianMD, testi diversi | utente | `docs/launch/README.md` | +| ven 30 ott | r/selfhosted (New Project Friday) | utente | — | +| inizio novembre | r/gnome, r/linux; outreach Menon, Theo James, PyCoder's (§8.1); Showcase di r/developersIndia l'8 nov | utente | `outreach.md`, `emerging.md` | + +Obiettivo originale: 30+ stelle nelle 24 ore dello Show HN, per entrare nel trending Python (§9.2). Dopo il §10.4 il peso passa a TWIG, Phoronix/OMG! Ubuntu e Reddit. Criterio di verifica: visite uniche e stelle, non clone. + +**Stato al 19 ottobre 2026 (sera).** + +- Risposta a Justin su dev.to: fatta dall'utente. +- Annuncio della 0.3 nelle Discussions dell'org, categoria Open Source AI: [#72](https://github.com/orgs/openapi/discussions/72), accanto a quello della 0.2 (#71). Al posto di attivare le Discussions sul repo si usano quelle dell'org: il ticker Pulse le linka da ogni README dell'org, e un secondo spazio dividerebbe una comunità ancora piccola. +- Link incrociati (azione 10): una riga in openapi-skills e openapi-python-sdk (sezione "Related projects"), in mcp-server ("Useful Resources") e nel README del profilo dell'org. Le PR vanno aperte dall'utente: il classificatore di auto mode blocca le scritture su altri repository. +- Glama: scheda ancora assente (404 su `glama.ai/mcp/servers/openapi/gknowledge`); serve il login dell'utente. + +### 10.4 Il post su Hacker News del 19 ottobre + +Il 19 ottobre alle 14:36 UTC l'utente ha pubblicato su HN [*The Second Brain Gnome Users Deserve. Go Ahead, HN. Flag This OpenSourceProject*](https://news.ycombinator.com/item?id=50153030), con link all'annuncio [#72](https://github.com/orgs/openapi/discussions/72) e non al repo, senza prefisso "Show HN". Alla pubblicazione: primo su /newest, visibile anche senza login, 1 punto, 0 commenti. + +- **Contesto dell'account** (`hacker-news.firebaseio.com/v0/user/francescobianco`): karma 8; i post del 3, 4, 10 e 13 ottobre e uno del 29 settembre risultano `dead`. +- **Rischi segnalati e accettati**: titolo che invita al flag, link a una pagina di annuncio invece che al repo, assenza da /show, effetto su un eventuale Show HN successivo. Proposta di cancellarlo finché aveva 0 commenti: **rifiutata**. L'utente accetta di perdere il lancio HN pianificato e sta preparando un repository separato per far crescere il karma dell'account. +- **Conseguenza per il piano**: lo Show HN del 27/28 ottobre esce dalla sequenza di §10.3. HN resta un canale dell'utente, gestito alle sue condizioni; non va più riproposto nei piani. +- **Da osservare**: punti, commenti e stato `dead` o `flagged` dell'item 50153030; referrer `news.ycombinator.com` nel traffico del repo e della discussione #72. diff --git a/TODO.md b/TODO.md index 9b1c83a..15de91b 100644 --- a/TODO.md +++ b/TODO.md @@ -10,18 +10,18 @@ Flatpak (the `.deb` and `install.sh` do nothing for Fedora, Arch or openSUSE use - [x] Flatpak build is green in CI (`appstreamcli compose` succeeds since the GNOME 51 bump); every release attaches a bundle and `repos.yml` publishes the remote at `openapi.github.io/gknowledge` (closes #24). - [x] `flatpak install --user https://openapi.github.io/gknowledge/io.gknowledge.Gknowledge.flatpakref` works on Ubuntu (2026-10-19): pulls GNOME 51 from Flathub, installs 0.2.2, the app launches. - [x] Inside the Flatpak, New Project failed with "disk I/O error" (SQLite WAL needs shared memory the document portal does not provide); the store no longer uses WAL and converts old databases. Project creation, PDF/Markdown import, ingest, query and drift check verified on a portal path (2026-10-19). -- [ ] Inside the Flatpak, by hand: create a project, import through the file chooser, ingest, reopen after a restart. -- [ ] Verify on a non-Ubuntu distro (Fedora VM or toolbox) before replying to Justin. +- [x] Inside the Flatpak, by hand: create a project, import through the file chooser, ingest, reopen after a restart (2026-10-19). +- [ ] Verify on a non-Ubuntu distro: Justin will install the Flatpak on Fedora 44 the week of 2026-10-20 and open issues for anything that breaks (GitHub `justinf555`); triage them first. - [x] README: badge and comparison table no longer say "Flatpak planned" (install section left as is). - [x] Vendor `pypdf` 6.19.0 in the manifest (the 0.2.2 bundle has `No module named 'pypdf'`, so PDF import fails). Builds green on PR #42. -- [ ] Release 0.3.0 (prepared 2026-10-19: version, CHANGELOG, MetaInfo, release notes with the Flatpak line): test the CI bundle end to end, merge, tag `v0.3.0`, then reinstall from the Pages remote and check `flatpak update`. +- [x] Release 0.3.0, tagged 2026-10-19: `.deb` and `.flatpak` on the release, `gknowledge-mcp` 0.3.0 on PyPI. A fresh install from the Pages flatpakref works, and the old ID's ref carries the end-of-life-rebase to the new one. - [x] CI and release Flatpak jobs are blocking (no `continue-on-error`); CI uploads an installable `gknowledge-dev.flatpak` artifact for every PR. - [ ] Flathub itself stays paused (AI-assisted code policy, see P0 below); say so plainly if asked, and point to the Pages remote. Develop against the runtime users get - [x] `make start-flatpak`: the `make start` loop run inside `org.gnome.Platform` (version read from the manifest), so host GTK/libadwaita differences show up before release. - [x] CONTRIBUTING documents `make start-flatpak`. -- [ ] With Justin's permission, link his GNOME SDK setup write-up from CONTRIBUTING. +- [x] With Justin's permission ([reply of 2026-10-19](https://dev.to/fromthearchitect/comment/3ia9i)), CONTRIBUTING links his GNOME SDK setup write-up (Part 1 of his GNOME + Rust series). Drift, not hallucination - [x] `core/lint.py`: `ChangeDetector` flags ingested sources whose original file no longer matches the ingested hash, with the pages that cite them. @@ -93,7 +93,7 @@ Speed and feedback - [ ] Build from `git`/`archive` sources instead of `type: dir` (`pypdf` vendored). - [ ] Complete MetaInfo: screenshots (URLs still missing; developer, urls, branding added), `developer`, `url`, branding colors, release notes, summary of 35 characters or fewer. - [ ] Make `flatpak-builder-lint` pass with no exceptions. -- [ ] Add a `.doap` file. (CI workflows for tests, metadata validation and Flatpak build exist; Flatpak job is non-blocking until proven.) +- [ ] Add a `.doap` file. (CI workflows for tests, metadata validation and Flatpak build exist; Flatpak job is blocking since 0.3.0.) - [ ] Open the `flathub/flathub` submission PR; verify the developer at merge. ## P0b: GNOME and Ubuntu integration (gedit-style) @@ -210,7 +210,7 @@ Tasks: ## Distribution and community -- [ ] Release workflow exists (`.github/workflows/release.yml`, builds a `.flatpak` bundle on `v*` tags); push the first tag once the Flatpak build is verified. +- [x] Release workflow exists (`.github/workflows/release.yml`, builds a `.flatpak` bundle on `v*` tags); first verified Flatpak release is v0.3.0. - [ ] AUR package (`gknowledge`), ideally maintained by a second person. - [ ] Release notes in MetaInfo for every release; monthly cadence at least. - [ ] Announce on This Week in GNOME via `#thisweek:gnome.org` the week of the Flathub merge. diff --git a/docs/launch/README.md b/docs/launch/README.md index 5b93fda..ca3fe2e 100644 --- a/docs/launch/README.md +++ b/docs/launch/README.md @@ -42,10 +42,11 @@ This replays the steps that took comparable projects from zero to thousands of s > - You can use your own ChatGPT Plus/Pro plan through OpenAI's new "Sign in with ChatGPT" for local apps, so there is no API key and nobody resells tokens. Ollama and any OpenAI-compatible endpoint work too. > - It avoids the usual LLM-wiki mess: no empty stub pages, duplicate names are merged, minor names stay mentions until a second source cites them. > - It ships an MCP server, so Claude Code or Codex can search and grow the same wiki. +> - Pages go stale when their source changes, not because the model hallucinates: it flags sources whose original file changed since ingest and lets you update them. > -> Install on Ubuntu/Debian: `curl -fsSL https://github.com/openapi/gknowledge/releases/latest/download/install.sh | bash` +> Install on any distro with Flatpak: `flatpak install --user https://openapi.github.io/gknowledge/io.github.openapi.Gknowledge.flatpakref` (or a one-line `.deb` installer for Ubuntu/Debian). > -> It's early (v0.2). I'd love feedback on the ingestion quality and on what you'd need to switch from Obsidian plus plugins. +> It's early (v0.3). I'd love feedback on the ingestion quality and on what you'd need to switch from Obsidian plus plugins. ## X / Mastodon thread @@ -53,7 +54,7 @@ This replays the steps that took comparable projects from zero to thousands of s 2. No Electron, no Tauri: GTK 4 + Libadwaita. The wiki is a plain folder you can open in Obsidian. 3. Bring your own brain: your ChatGPT plan via "Sign in with ChatGPT" (no API key), Ollama, or any OpenAI-compatible endpoint. 4. Agents welcome: `claude mcp add gknowledge -- gknowledge-mcp ~/Knowledge/project` -5. MIT licensed. One-line install for Ubuntu. ⭐ github.com/openapi/gknowledge +5. MIT licensed. Flatpak for any distro, one-line install for Ubuntu. ⭐ github.com/openapi/gknowledge ## Reddit @@ -66,7 +67,7 @@ Each post: one screenshot or the demo, two short paragraphs, the install line, a ## GNOME channels -- **This Week in GNOME** (Matrix room `#thisweek:gnome.org`): "gknowledge 0.2 is out: a native GTK 4 and Libadwaita app that turns your documents into a linked, cited wiki, offline by default, with optional local or ChatGPT models." +- **This Week in GNOME** (Matrix room `#thisweek:gnome.org`): "gknowledge 0.3 is out: a native GTK 4 and Libadwaita app that turns your documents into a linked, cited wiki, offline by default, with optional local or ChatGPT models. New in 0.3: a Flatpak for any distribution (`flatpak install --user https://openapi.github.io/gknowledge/io.github.openapi.Gknowledge.flatpakref`), PDF import inside the sandbox, and sources that changed since ingest are flagged so the pages built from them can be updated." - **Phoronix tip and OMG! Ubuntu tip:** link to the release page, the one-liner, and two screenshots. ## Chinese communities