francescobianco · Oct 13, 2026 · Oct 13, 2026
diff --git a/build-aux/debian/changelog b/build-aux/debian/changelog
@@ -0,0 +1,5 @@
+gknowledge (0.2.2-1) unstable; urgency=medium
+
+  * Initial release. (Closes: #XXXXXX)
+
+ -- Francesco Bianco <info.francescobianco@gmail.com>  Tue, 13 Oct 2026 14:00:00 +0000
diff --git a/build-aux/debian/control b/build-aux/debian/control
@@ -0,0 +1,33 @@
+Source: gknowledge
+Section: utils
+Maintainer: Francesco Bianco <info.francescobianco@gmail.com>
+Build-Depends: debhelper-compat (= 14),
+               dh-python,
+               python3,
+               python3-pypdf <!nocheck>,
+Standards-Version: 4.7.4
+Homepage: https://github.com/openapi/gknowledge
+Vcs-Browser: https://github.com/openapi/gknowledge
+Vcs-Git: https://github.com/openapi/gknowledge.git
+
+Package: gknowledge
+Architecture: all
+Depends: gir1.2-adw-1,
+         gir1.2-gtk-4.0,
+         python3-gi,
+         ${misc:Depends},
+         ${python3:Depends},
+Recommends: python3-pypdf,
+Description: native GNOME app that turns documents into a cited wiki
+ gknowledge collects documents, notes and links (Markdown, text, PDF,
+ HTML, EPUB) and turns them into a linked Markdown wiki in which every
+ page records its sources. Questions are answered from the wiki with
+ numbered citations that link back to the pages they came from.
+ .
+ The knowledge base is a plain folder of Markdown files with wikilinks
+ and front matter, so it can be opened in other editors or kept in git.
+ .
+ It works fully offline with a built-in heuristic engine. Optionally it
+ can use a local model through Ollama or LM Studio, any OpenAI-compatible
+ endpoint, or the user's own ChatGPT plan. The gknowledge-mcp command
+ exposes the wiki to MCP clients such as coding agents.
diff --git a/build-aux/debian/copyright b/build-aux/debian/copyright
@@ -0,0 +1,43 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: gknowledge
+Upstream-Contact: https://github.com/openapi/gknowledge/issues
+Source: https://github.com/openapi/gknowledge
+
+Files: *
+Copyright: 2026 Openapi®
+License: Expat
+
+Files: data/io.gknowledge.Gknowledge.metainfo.xml
+Copyright: 2026 Openapi®
+License: CC0-1.0
+
+Files: debian/*
+Copyright: 2026 Francesco Bianco <info.francescobianco@gmail.com>
+License: Expat
+
+License: Expat
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+ .
+ The above copyright notice and this permission notice shall be included in all
+ copies or substantial portions of the Software.
+ .
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.
+
+License: CC0-1.0
+ To the extent possible under law, the author(s) have dedicated all copyright
+ and related and neighboring rights to this software to the public domain
+ worldwide. This software is distributed without any warranty.
+ .
+ On Debian systems, the complete text of the CC0 1.0 Universal license can be
+ found in "/usr/share/common-licenses/CC0-1.0".
diff --git a/build-aux/debian/docs b/build-aux/debian/docs
@@ -0,0 +1 @@
+README.md
diff --git a/build-aux/debian/gknowledge-mcp.1 b/build-aux/debian/gknowledge-mcp.1
@@ -0,0 +1,34 @@
+.TH GKNOWLEDGE-MCP 1 "October 2026" "gknowledge 0.2.2" "User Commands"
+.SH NAME
+gknowledge-mcp \- Model Context Protocol server for a gknowledge wiki
+.SH SYNOPSIS
+.B gknowledge-mcp
+.I PROJECT
+.SH DESCRIPTION
+.B gknowledge-mcp
+lets Model Context Protocol clients, such as coding agents, use a
+gknowledge project. It speaks JSON-RPC 2.0 over standard input and
+output and offers the tools search_wiki, read_page, list_pages, ask,
+add_source and recent_activity.
+.PP
+It is normally started by the MCP client, not by hand.
+.SH ARGUMENTS
+.TP
+.I PROJECT
+Path to a gknowledge project folder.
+.SH ENVIRONMENT
+.TP
+.B GKNOWLEDGE_PROJECT
+Project path, used when
+.I PROJECT
+is not given.
+.SH EXAMPLES
+Register the server with Claude Code:
+.PP
+.nf
+.RS
+claude mcp add gknowledge \-\- gknowledge\-mcp ~/Knowledge/my\-project
+.RE
+.fi
+.SH SEE ALSO
+.BR gknowledge (1)
diff --git a/build-aux/debian/gknowledge.1 b/build-aux/debian/gknowledge.1
@@ -0,0 +1,31 @@
+.TH GKNOWLEDGE 1 "October 2026" "gknowledge 0.2.2" "User Commands"
+.SH NAME
+gknowledge \- native GNOME app that turns documents into a cited wiki
+.SH SYNOPSIS
+.B gknowledge
+[\fIGTK-OPTIONS\fR]
+.SH DESCRIPTION
+.B gknowledge
+collects documents, notes and links and turns them into a linked
+Markdown wiki in which every page records its sources. Questions are
+answered from the wiki with numbered citations.
+.PP
+A project is a plain folder of Markdown files with wikilinks and front
+matter, plus an SQLite index. It can be opened in other Markdown editors
+or kept under version control.
+.PP
+The app works offline with a built-in engine. A model provider (Ollama,
+LM Studio, any OpenAI-compatible endpoint, or a ChatGPT plan) can be
+chosen in Preferences.
+.SH OPTIONS
+Standard GTK and GApplication options are accepted, for example
+.BR \-\-help .
+.SH FILES
+.TP
+.I $XDG_CONFIG_HOME/gknowledge/
+Recent projects and provider settings (defaults to
+.IR ~/.config/gknowledge/ ).
+.SH SEE ALSO
+.BR gknowledge\-mcp (1)
+.PP
+https://github.com/openapi/gknowledge
diff --git a/build-aux/debian/gknowledge.manpages b/build-aux/debian/gknowledge.manpages
@@ -0,0 +1,2 @@
+debian/gknowledge.1
+debian/gknowledge-mcp.1
diff --git a/build-aux/debian/rules b/build-aux/debian/rules
@@ -0,0 +1,20 @@
+#!/usr/bin/make -f
+
+%:
+	dh $@ --with python3
+
+# The upstream Makefile has no build step; its default target only prints help.
+override_dh_auto_build:
+
+override_dh_auto_install:
+	$(MAKE) install DESTDIR=$(CURDIR)/debian/gknowledge PREFIX=/usr PYTHON=/usr/bin/python3
+	find debian/gknowledge -name __pycache__ -type d -prune -exec rm -rf {} +
+
+override_dh_auto_test:
+ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS)))
+	python3 tests/test_core.py
+endif
+
+# The package lives in a private directory, not in dist-packages.
+override_dh_python3:
+	dh_python3 /usr/share/gknowledge
diff --git a/build-aux/debian/source/format b/build-aux/debian/source/format
@@ -0,0 +1 @@
+3.0 (quilt)
diff --git a/build-aux/debian/upstream/metadata b/build-aux/debian/upstream/metadata
@@ -0,0 +1,4 @@
+Bug-Database: https://github.com/openapi/gknowledge/issues
+Bug-Submit: https://github.com/openapi/gknowledge/issues/new
+Repository: https://github.com/openapi/gknowledge.git
+Repository-Browse: https://github.com/openapi/gknowledge
diff --git a/build-aux/debian/watch b/build-aux/debian/watch
@@ -0,0 +1,4 @@
+version=4
+opts="filenamemangle=s%(?:.*?)?v?(\d[\d.]*)\.tar\.gz%gknowledge-$1.tar.gz%" \
+  https://github.com/openapi/gknowledge/tags \
+  (?:.*?/)?v?(\d[\d.]*)\.tar\.gz
diff --git a/docs/packaging/debian.md b/docs/packaging/debian.md
@@ -0,0 +1,92 @@
+# Getting gknowledge into Debian and Ubuntu
+
+The goal is `sudo apt install gknowledge` on stock Debian and Ubuntu. Ubuntu imports new packages from Debian unstable automatically, so a package accepted in Debian lands in Ubuntu **universe** at the next sync. This is the route other GTK Python apps have taken: Apostrophe, for example, is maintained by the Debian GNOME team and reaches Ubuntu the same way.
+
+The source packaging lives in [`build-aux/debian/`](../../build-aux/debian). It is the `debian/` directory to copy into a packaging repository on Salsa (Debian's GitLab); it is not used by our own `.deb` script.
+
+## Build and check it locally
+
+```sh
+git archive --format=tar.gz --prefix=gknowledge-0.2.2/ v0.2.2 > ../gknowledge_0.2.2.orig.tar.gz
+tar -C .. -xzf ../gknowledge_0.2.2.orig.tar.gz
+cp -r build-aux/debian ../gknowledge-0.2.2/debian
+cd ../gknowledge-0.2.2 && dpkg-buildpackage -us -uc
+lintian -I --pedantic ../gknowledge_0.2.2-1_*.changes
+```
+
+On a host without debhelper, run the same steps in a `debian:sid` container with `build-essential devscripts debhelper dh-python python3 python3-pypdf lintian` installed.
+
+Last checked on 2026-10-13 in `debian:sid`: builds, the core tests run during the build and pass, the package installs and the GTK 4 and Libadwaita modules import. Lintian only reports the placeholder ITP bug number, which is filled in after step 1, and informational notes.
+
+## Steps
+
+1. **File the ITP** (Intent To Package) against the `wnpp` pseudo-package, with the text below. Use `reportbug wnpp` or email `submit@bugs.debian.org`. The bug number replaces `#XXXXXX` in `debian/changelog`.
+2. **Ask the Debian GNOME team** whether they will co-maintain it (message below). If they accept, `Maintainer:` becomes `Debian GNOME Maintainers <pkg-gnome-maintainers@lists.alioth.debian.org>` and we go in `Uploaders:`, and the repository moves under `salsa.debian.org/gnome-team/`.
+3. **Find a sponsor.** Uploading to Debian needs a Debian Developer. Upload the source package to [mentors.debian.net](https://mentors.debian.net) and file an RFS (Request For Sponsorship) bug against `sponsorship-requests`, or ask the GNOME team directly.
+4. **Wait for NEW.** New packages go through the ftp-masters' NEW queue, which typically takes days to weeks.
+5. **Ubuntu.** Once in unstable, the package syncs into the current Ubuntu development release automatically. Older Ubuntu releases keep using our `.deb` or the Snap.
+
+Each new upstream release then needs a new `debian/changelog` entry and an upload; `debian/watch` lets `uscan` find new tags.
+
+## ITP text
+
+```
+Subject: ITP: gknowledge -- native GNOME app that turns documents into a cited wiki
+Package: wnpp
+Severity: wishlist
+Owner: Francesco Bianco <info.francescobianco@gmail.com>
+X-Debbugs-Cc: debian-devel@lists.debian.org, debian-gtk-gnome@lists.debian.org
+
+* Package name    : gknowledge
+  Version         : 0.2.2
+  Upstream Contact: https://github.com/openapi/gknowledge/issues
+* URL             : https://github.com/openapi/gknowledge
+* License         : Expat (code), CC0-1.0 (AppStream metadata)
+  Programming Lang: Python
+  Description     : native GNOME app that turns documents into a cited wiki
+
+gknowledge collects documents, notes and links (Markdown, text, PDF,
+HTML, EPUB) and turns them into a linked Markdown wiki in which every
+page records its sources. Questions are answered from the wiki with
+numbered citations. It works fully offline with a built-in engine and
+can optionally use a local model (Ollama, LM Studio), any
+OpenAI-compatible endpoint, or the user's own ChatGPT plan. It also
+ships an MCP server so coding agents can use the same wiki.
+
+It is a GTK 4 / Libadwaita app with no dependencies outside the archive
+(python3-gi, gir1.2-gtk-4.0, gir1.2-adw-1, optionally python3-pypdf).
+Similar apps in Debian are general note editors such as Apostrophe;
+none builds a cited knowledge base from source documents.
+
+I am upstream and will maintain the package, ideally within the Debian
+GNOME team. Packaging is ready and lintian-clean apart from this bug
+number: https://github.com/openapi/gknowledge/tree/main/build-aux/debian
+I need a sponsor.
+```
+
+## Message to the Debian GNOME team
+
+To: `debian-gtk-gnome@lists.debian.org`
+
+```
+Subject: Team maintenance for gknowledge (GTK 4/Libadwaita, ITP #XXXXXX)
+
+Hello,
+
+I'm the upstream developer of gknowledge, a GTK 4 and Libadwaita app
+written in Python that turns documents into a linked Markdown wiki with
+sources and cited answers. It works offline and only depends on
+python3-gi, gir1.2-gtk-4.0 and gir1.2-adw-1 (python3-pypdf optional).
+
+I've filed ITP #XXXXXX and prepared the packaging (debhelper 14,
+dh-python, private module directory, man pages, lintian-clean apart
+from the ITP number):
+https://github.com/openapi/gknowledge/tree/main/build-aux/debian
+
+Would the team be willing to host it on Salsa under gnome-team, with me
+as an uploader, and could someone sponsor the first upload? I'm happy
+to follow the team's packaging conventions and to take care of updates.
+
+Thanks,
+Francesco Bianco
+```