Building a GitHub-Backed Knowledge Portfolio: Lessons from MyZubster, Zorgax, and an Open Source Documentation Proposal

How do you turn development activity into a public knowledge portfolio without confusing a GitHub commit, an individual contribution, and independently verified expertise?

By Daniel Ioni — Founder & Product Builder, MyZubster

Introduction: GitHub shows our code, but does it communicate our knowledge?

A developer's GitHub account can contain years of valuable work: commits, experiments, pull requests, documentation, tests, deployment configurations, and abandoned prototypes.

However, a commit history does not automatically explain what someone learned, which problems they investigated, or how their activities relate to particular technical domains.

The opposite problem is equally important.

A professional profile can list dozens of skills without showing any supporting work. A repository can be linked without explaining the person's involvement. A pull request can be presented as a contribution even when the upstream maintainers have not accepted it.

At MyZubster, we wanted to explore a different approach.

Our objective was to build a workflow that connects:

1. An authenticated user identity.
2. Structured descriptions of technical activities.
3. Public GitHub commits and pull requests, where available.
4. Other clearly labeled documentation when the original evidence cannot be independently accessed.
5. A GitHub profile README that the user can review before publication.

We implemented this workflow through Zorgax, an assistant integrated into the MyZubster ecosystem, and a feature called Knowledge Cards.

This article describes our implementation, the problems we encountered, the decisions behind the system, and the lessons that might be useful to other open source developers.

It also covers a real example involving a proposed change to Monero's Wallet RPC documentation.

The guiding principle throughout the project was simple:

Evidence should help people understand technical work without claiming to prove more than it actually proves.

---

1. The problem we were trying to solve

MyZubster is an evolving open source ecosystem that includes community features, developer workflows, AI-assisted experiences, and other interconnected projects.

As the ecosystem developed, we accumulated different types of technical work across multiple repositories and GitHub accounts.

Some activities were straightforward to reference: they had publicly accessible commits showing specific changes.

Other activities were more difficult to represent.

For example, what should happen when someone prepares a documentation improvement in a fork, submits a pull request, and the pull request is subsequently closed without being merged?

Should that activity disappear from their professional history?

Certainly not. Preparing an upstream proposal may involve reading documentation, understanding an API, identifying ambiguity, and communicating a proposed solution.

But should the portfolio describe it as an accepted contribution to the upstream project?

Also no.

The activity can be documented without changing its actual status.

We identified several requirements for our system:

• Developers should be able to describe activities in their own words.
• Public source references should be checked before receiving a verified-accessibility label.
• A source being publicly accessible should not automatically establish authorship or expertise.
• Documentation that cannot be independently verified should carry an explicit disclosure.
• Published cards should remain separate from the GitHub README until the user authorizes an update.
• README synchronization should preserve existing profile content.
• Repeated synchronization should not create duplicate sections.

These requirements became the foundation of Knowledge Cards.

---

2. Knowledge Cards: representing activities as structured information

A Knowledge Card is a structured public record of an activity or technical knowledge area.

Rather than asking someone to select a skill and assigning it an arbitrary score, our system asks the user to explain what they actually did.

A card contains several fields.

Field	Purpose
Title	Identifies the activity or knowledge area
Domain	Describes the related technical subjects
Description	Records the activities declared by the owner
Evidence	Stores relevant source references
Verification note	Explains what has and has not been independently established
Publication status	Separates private drafts from publicly accessible cards

This structure is important because these fields represent different kinds of information.

Consider the following fictionalized example:

Title: Development of API Authentication Modules

Domain: JavaScript, Node.js, Authentication, Security

Declared activities: Implemented and tested an API authentication module.

Evidence: A public GitHub commit containing the relevant implementation and tests.

Verification status: The public source has been checked for accessibility. The commit alone does not independently certify personal expertise.

The description is a statement by the owner.

The GitHub reference points to an inspectable technical artifact.

The verification note explains the limits of the available evidence.

Keeping these elements separate makes the profile more informative.

It also prevents the application from silently transforming a user's description into a supposedly certified achievement.

Our published Knowledge Cards

During the development of this feature, we created three public cards associated with our work:

1. MyZubster ecosystem development

Documents development, coordination, experimentation, and related repository activity.

View the MyZubster Knowledge Card

2. MyZubster Space Station security and privacy modules

Documents activity involving digital identity modules, MRV data handling, technical specifications, tests, and GitHub Actions workflows.

View the Space Station Knowledge Card

3. Monero Wallet RPC documentation proposal

Documents a proposed clarification to Monero Docs, explicitly identifying the proposal as not merged upstream.

View the Monero Docs Knowledge Card

These three examples helped us test different evidence scenarios rather than designing the system exclusively around successful, publicly visible pull requests.

---

3. Connecting GitHub evidence to existing Knowledge Cards

One of our first technical challenges was allowing a developer to add a GitHub reference to a card that already exists.

We didn't want users to recreate an entire Knowledge Card every time they found another relevant commit.

We therefore introduced a dedicated workflow for attaching GitHub evidence to an existing card.

The process is:

1. The authenticated owner selects a Knowledge Card.
2. They provide a GitHub commit or pull request URL.
3. The server validates the URL structure.
4. The server checks whether the referenced GitHub resource is publicly accessible.
5. The user explicitly confirms the operation.
6. The verified-accessibility reference is stored with the card.

The important distinction is that the server doesn't trust a URL merely because a user submitted it.

Step 1: Validate the URL

A GitHub URL can look legitimate while containing an incomplete commit identifier or pointing to an unsupported resource.

For README synchronization, we implemented a format check that accepts a GitHub pull request number or a complete 40-character hexadecimal commit SHA.

The following is based on our actual client-side validation logic:

const publicGithubSourceUrl = value => {
  const url = String(value || '').trim();

  return /^https:\/\/github\.com\/[a-z\d_.-]+\/[a-z\d_.-]+\/(?:pull\/[1-9]\d*|commit\/[a-f\d]{40})\/?$/i.test(url)
    ? url
    : '';
};

This check serves a limited but important purpose.

It identifies URLs with the expected structure.

It does not establish that the resource exists.

A perfectly formatted URL may still reference an unavailable commit or private repository.

Consequently, structural validation and source accessibility checking are separate operations.

Step 2: Check the GitHub resource

For the source attachment workflow, our backend uses the public GitHub API.

For a commit, the relevant GitHub REST endpoint has this general form:

GET https://api.github.com/repos/{owner}/{repo}/commits/{sha}

For pull requests, we use the corresponding GitHub pull request endpoint.

The backend handles unsuccessful responses instead of blindly storing a reference as verified.

We also avoid sending application OAuth credentials to GitHub merely to check evidence that is supposed to be publicly accessible.

This prevents a particular category of misleading results: a resource might be visible to an authenticated account but unavailable to everyone else.

Step 3: Store the evidence with the correct meaning

When a public GitHub resource is successfully checked, the card can store a description such as:

Public GitHub source accessible. Availability was checked. This does not automatically certify competence or personal attribution.

This wording is deliberate.

A successful API response means the resource was accessible during the check.

The API response may also contain information about GitHub author accounts and commit metadata.

However, an application should not silently turn that information into an independent identity certification.

A publicly accessible commit is evidence that the commit exists.

Additional claims require additional evidence.

---

4. A real debugging lesson: the missing character in a commit SHA

During development, one of our Knowledge Cards contained a GitHub source that appeared correct at first glance.

It pointed to our Space Station repository and referenced a security-related commit.

But the link did not pass the validation used by our README importer.

Initially, this looked like a problem with the import process.

After investigating, we found the actual issue: the manually entered commit SHA was missing its final character.

The original reference ended in:

...3eb0c7d050428eb63077c8926dcb3ab03d9204d

The complete identifier ended in:

...3eb0c7d050428eb63077c8926dcb3ab03d9204d5

That single character mattered.

We connected the complete commit through the GitHub evidence workflow, allowing the system to check and store the valid reference.

Inspect the complete Space Station commit

The commit includes work associated with digital identity, privacy-related modules, supporting documentation, tests, and CI configuration.

What this taught us

There are two distinct integrity problems when importing developer evidence.

Structural integrity: Is the submitted reference well formed?

Source availability: Can the referenced artifact actually be retrieved from its supposed public location?

Our workflow now treats these as separate concerns.

The README importer also filters out malformed GitHub evidence, so an invalid manually recorded link does not automatically appear in the published profile.

One remaining maintenance detail is worth disclosing: the original malformed reference was preserved in the public Knowledge Card alongside the corrected one. The README correctly excludes it, but the card itself still requires a separate cleanup operation.

This is an example of why correcting derived output is not always the same as cleaning up the underlying data.

---

5. A different evidence problem: our Monero Docs proposal

Not every developer activity ends with a successfully merged pull request.

Our work involving Monero Docs provided a useful example.

Using the GitHub account DanielIoni-creator, I prepared a small documentation clarification in a fork of the Monero Docs repository.

The change concerned the pending parameter of the Monero Wallet RPC method get_transfers.

The original documentation described the parameter as:

Include pending transfers.

The proposed wording was:

Include pending, unconfirmed outgoing transfers.

The intention was to clarify the scope of the parameter and reduce ambiguity for developers using the Wallet RPC documentation.

The change was submitted through pull request #389 to the Monero Docs project.

The pull request was subsequently closed without being merged.

That detail is part of the activity's history, and it should remain visible whenever we describe it.

There was another complication.

During our verification, the original fork and pull request were not accessible without authentication.

Our connected GitHub account could retrieve the relevant information, but we could not treat that access as equivalent to public, independent accessibility.

The solution: a public contribution dossier

Instead of presenting the unavailable source as a publicly verified contribution, we prepared a public document in the MyZubster repository.

It explains:

• The original documentation wording.
• The proposed clarification.
• The affected Wallet RPC method.
• The original commit reference.
• The upstream pull request reference.
• The fact that the pull request was closed without being merged.
• The limitations of independent verification.

Read the public Monero Docs contribution dossier

We then attached this dossier to a dedicated Knowledge Card.

View the Monero Docs Knowledge Card

Importantly, we did not assign the dossier the same status as a public GitHub commit whose availability had been checked through the GitHub API.

Instead, it receives an explicit label:

Self-declared documentation — not independently verified.

This is a distinction other developer portfolio platforms may find useful.

There is value in recording proposals, experiments, unsuccessful submissions, and learning experiences.

But we should not erase the difference between submitting a proposal and having it accepted by upstream maintainers.

The public dossier documents our account of the activity. It does not prove that Monero accepted the proposal, endorsed MyZubster, or independently certified my expertise.

---

6. Separating evidence categories instead of forcing everything into one model

The Monero Docs experience revealed a broader architectural lesson.

A single evidence type is not sufficient for every developer activity.

For example, a system might encounter:

Evidence type	What it can establish	Important limitation
Public GitHub commit	The referenced commit was accessible during the check	Does not independently certify expertise
Public GitHub pull request	The referenced PR was accessible during the check	A submitted PR may not be merged
Owner-authored public document	The owner's description of an activity is available to readers	The original activity may not be independently verified
Repository documentation	Technical details about a project or implementation	Does not automatically establish an individual's involvement

This led us to support public documentation references while labeling them separately from checked GitHub commits and pull requests.

For README synchronization, we introduced additional URL handling for public Markdown documents hosted on GitHub.

The key idea is that an accepted documentation URL should not increment the same counter used for verified-accessibility GitHub commits and pull requests.

Conceptually, the importer tracks separate categories:

let sourceCount = 0;
let documentCount = 0;

for (const evidence of evidenceItems) {
  if (evidence.isDocument) {
    documentCount++;
  } else {
    sourceCount++;
  }
}

This is a simplified illustration of the separation implemented in our importer.

The output then uses different labels for different evidence types.

For the published Monero card, the README explicitly identifies the linked material as documentation that has not been independently verified.

That distinction remains visible to anyone reading the GitHub profile.

---

7. GitHub profile synchronization: preserving existing content

After developing the Knowledge Cards, we needed a way to make them discoverable.

A GitHub profile README was a natural destination.

It is familiar to developers, appears on GitHub profiles, and allows us to provide direct links to technical work.

But updating a README introduces an obvious risk.

A developer may already have manually written their biography, project descriptions, contact details, contribution guidelines, or other important information.

Replacing the entire README simply to add Knowledge Cards would be unacceptable.

The managed-section approach

We introduced a dedicated section in the profile README, identified using explicit start and end markers.

<!-- MYZUBSTER-KNOWLEDGE-CARDS:START -->

## Knowledge Cards

<!-- Generated and reviewed content goes here -->

<!-- MYZUBSTER-KNOWLEDGE-CARDS:END -->

These markers define the area that Zorgax manages.

The goal is to preserve everything outside that area.

If a managed section already exists, synchronization replaces the existing managed content instead of appending a second copy.

This behavior is commonly described as idempotence.

An idempotent update can be repeated without producing additional unintended changes.

For example, importing the same three Knowledge Cards multiple times should not result in nine duplicated entries or multiple managed sections.

Why idempotence matters

Imagine a developer who synchronizes their portfolio after every significant project update.

Without an idempotent process, each synchronization could introduce duplicate content that requires manual cleanup.

Worse, a user might become reluctant to synchronize at all because they cannot predict what the application will change.

Predictable updates are essential when an application modifies content on an external platform.

Our implementation uses the managed section to make this behavior easier to reason about and verify.

---

8. An important safety requirement: never overwrite an unreadable README

During testing, we encountered a problem that could have resulted in a dangerous update.

Zorgax was temporarily unable to retrieve the current GitHub profile README.

At this point, the system had two possible choices.

It could continue using incomplete information.

Or it could refuse to prepare the update until the existing README was available.

We chose the second option.

The importer stops when the current profile snapshot is incomplete or the README is unavailable.

The user sees a message explaining that the existing README must be loaded first to avoid overwriting information.

This is a practical application of a general engineering principle:

When performing a potentially destructive operation, missing information should be treated as a reason to stop, not permission to guess.

This principle is applicable far beyond GitHub.

It matters whenever software synchronizes data between systems, particularly when one system is the authoritative source for information that users maintain manually.

Explicit user approval

Even after successfully preparing an updated README, Zorgax does not immediately publish it.

The user must:

1. Load the existing GitHub profile information.
2. Generate an updated preview.
3. Review the proposed content.
4. Explicitly approve the preview.
5. Authorize publication.

The workflow separates generating content from publishing content.

That separation is especially important when the generated material makes public statements about someone's experience or technical contributions.

---

9. Another debugging lesson: text generation must preserve meaning and punctuation

The project also uncovered a smaller but instructive bug.

When we added a verified-accessibility GitHub source to a Knowledge Card, the backend updated its verification note.

If a user had already written a custom note, the system preserved that text and appended its standard GitHub evidence disclosure.

Unfortunately, our earlier implementation could remove the original note's final punctuation.

The result looked like this:

... does not independently certify expertise At least
one public GitHub source has been linked ...

The sentences were individually correct, but the combined text was not.

This might seem minor compared with an authentication or data-integrity issue.

However, a public portfolio is also a communication product.

Poorly assembled verification language can confuse readers precisely where clarity is most important.

We changed the note-generation logic so that it normalizes the boundary between existing text and the appended standard statement.

We also had to handle a second requirement.

Some cards had already been published with the incorrect punctuation.

Simply correcting the function for newly added evidence would not repair those existing records.

Our solution supports explicitly refreshing an existing card's verification note.

Testing repeated updates

We tested two behaviors:

• A previously published note with the missing punctuation is repaired.
• Running the refresh again does not append the same standard disclosure twice.

Conceptually:

const repaired = refreshVerificationNote(existingNote);

const repeated = refreshVerificationNote(repaired);

expect(repeated).toBe(repaired);

This is illustrative test code, rather than a complete extract of our backend tests.

The real lesson is that idempotence also matters for generated text.

When an application appends disclosures, warnings, or explanatory sentences, repeated operations should not progressively damage the content.

After deploying the correction, we refreshed the affected Knowledge Card and synchronized the GitHub profile again.

We subsequently checked the public README to confirm that the corrected punctuation was present.

---

10. What our final GitHub profile contains

After completing these iterations, we verified the public README associated with the GitHub account @myzubster.

The managed section contained:

Published content	Count
Public Knowledge Cards	3
Imported public GitHub commit references	3
Public self-declared documentation references	1
Managed Knowledge Card sections	1

The three Knowledge Cards cover different kinds of work.

MyZubster ecosystem development documents work associated with the platform and supporting repository activity.

Space Station security and privacy modules links to a complete public commit covering identity- and privacy-related implementation work.

Monero Wallet RPC documentation describes a specific proposed documentation change while clearly acknowledging that the upstream PR was closed without being merged.

The profile does not treat these records as equivalent forms of evidence.

Instead, each card provides the context required to interpret its references.

Explore the updated GitHub profile

---

11. Technical and architectural lessons

Working through these examples helped us identify several design principles that could be useful to other developers building contribution platforms, professional portfolios, knowledge systems, or AI-assisted publishing tools.

A. Treat user declarations and independently accessible sources differently

A user's description is valuable information.

But it should remain distinguishable from information that an external reader can verify independently.

Both categories can coexist in the same application when their status is explicit.

B. Verify what you actually claim to verify

When our system checks a GitHub reference, it is checking the accessibility of that resource.

It is not awarding a qualification or independently investigating every claim in the accompanying description.

Verification systems become more trustworthy when they describe the precise scope of their checks.

C. Model unsuccessful contributions accurately

Software engineering involves experimentation.

A proposal can be rejected.

A pull request can be closed.

A prototype can remain unpublished.

Developers can still explain what they attempted, why they attempted it, and what the work involved.

But a portfolio must distinguish those activities from accepted upstream contributions.

D. Protect user-authored content during synchronization

Automated updates should operate within clearly defined boundaries.

For our GitHub profile integration, this means preserving unrelated README content, detecting an existing managed section, and stopping when the original README cannot be retrieved.

E. Require explicit approval for public identity changes

Generating a suggested description is not the same as obtaining permission to publish it.

The user must control the final public representation of their work.

F. Test data quality, not just application functionality

The missing SHA character and punctuation bug demonstrated that a system can behave as implemented while still producing an undesirable result.

Tests should include malformed references, repeated updates, previously published content, and other realistic scenarios.

G. Make evidence understandable to humans

Even a technically correct source link needs context.

Readers should be able to understand why it was attached, what activity it relates to, and whether it actually supports the accompanying description.

This is particularly important when a knowledge platform uses AI to assist with generating public content.

---

12. Where we go from here

This implementation is a foundation rather than the final version of our knowledge system.

There are several areas we intend to continue exploring.

One is improving source management for already published cards, including the safe removal of outdated or malformed references without affecting valid evidence.

Another is making verification states easier for readers to understand.

We also want to improve how technical activities can be discovered through the broader MyZubster ecosystem, so that a Knowledge Card becomes more than a section in a GitHub README.

The long-term objective is not to assign developers an automated expertise score.

It is to improve how technical knowledge, documented activities, project references, and individual statements can be connected and explored.

GitHub provides a strong technical foundation for this work, but GitHub alone does not tell the complete story.

A structured knowledge layer can help provide the missing context.

---

Conclusion: documenting technical work without overstating it

The most important outcome of this project was not simply publishing three Knowledge Cards.

It was building and testing a workflow that respects the distinction between an activity, a supporting artifact, and an independently established claim.

Our public GitHub commits provide inspectable technical references.

Our Monero Docs dossier documents a proposed change and openly explains why it should not be presented as an accepted upstream contribution.

Our README synchronization workflow preserves existing content and requires explicit approval.

And the bugs we encountered reminded us that even small implementation details can affect the integrity of information published under someone's identity.

For developers building portfolio tools, open source contribution systems, or AI-assisted knowledge platforms, that may be the most transferable lesson:

Make technical activities discoverable, make evidence inspectable, and make the limitations of that evidence just as visible.

The result is not an automatically certified developer profile.

It is something potentially more useful: a public record that readers can investigate and interpret for themselves.

---

Explore the project

MyZubster ecosystem

• MyZubster website
• Main open source repository
• Zorgax
• GitHub profile

Published Knowledge Cards

• MyZubster ecosystem development
• Space Station security, digital identity, and privacy
• Monero Wallet RPC documentation proposal

Technical references

• Space Station security and privacy commit
• Public documentation of the Monero Docs proposal
• Knowledge Card documentation and README integration PR
• Verification-note punctuation and idempotence fix

This article documents development activities and implementation decisions in the MyZubster ecosystem. The Monero Docs proposal discussed here was not merged into the upstream project. None of the Knowledge Cards should be interpreted as an independent professional certification.

Author: Daniel Ioni

Founder & Product Builder — MyZubster